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

Producer Readiness Checklist For Async Contract Changes — Проверка готовности producers к безопасному выпуску изменений async contracts

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

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

Этот документ фиксирует producer-side release-gate для изменений в async contracts платформы.

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

  • что обязан проверить producer перед выпуском новой event_version, schema_family change или semantic change;
  • как producer должен оценивать downstream impact на consumers, replay, DLQ, observability и external webhook projections;
  • какие проверки являются общими для всех release units, а какие зависят от доменного контура;
  • как превратить version policy и execution matrices в реальный producer discipline.

Документ не заменяет schema policy, channel catalog или release plan. Он является producer-side checklist, по которому можно принять решение, можно ли безопасно выпускать contract change.

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

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

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

  • version evolution policy;
  • consumer-side compatibility checklist;
  • webhook boundary checklist;

недостаточно проверять только downstream readers.

Нужен отдельный producer-side gate, потому что именно producer:

  • выбирает момент изменения контракта;
  • определяет shape и semantic drift;
  • влияет на replay behavior и version overlap;
  • может сломать сразу и internal consumers, и external webhook projections;
  • отвечает за то, чтобы новый contract был не просто “логичным локально”, а безопасным для всей цепочки.

Без этого compatibility discipline превращается в одностороннюю обязанность consumers.

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

Producer must prove change safety before emitting new contract behavior.

Это означает:

  • producer не может считать изменение безопасным только потому, что JSON остаётся валидным;
  • producer обязан думать не только о собственной bounded context логике, но и о downstream truth chain;
  • producer change не считается готовым, пока не оценены replay impact, observability impact, compatibility window и external projection consequences.

Общий Producer Readiness Checklist​

Перед выпуском изменения producer обязан подтвердить:

  1. Contract change type is explicitly classified: additive, bounded-semantic, or breaking.
  2. Existing field meanings remain stable or version bump is introduced.
  3. Bounded codes retain old meaning or compatibility plan exists.
  4. Replay impact is assessed explicitly.
  5. DLQ and retry consequences are understood for affected families.
  6. Critical consumers have been identified and informed.
  7. External webhook projection impact has been reviewed, if applicable.
  8. Observability fields and mismatch signals remain sufficient.
  9. Version overlap and retirement plan are documented.
  10. Forward-fix or rollback stance is known before emission starts.

RU-2 Supplier Intake And Canonicalization​

Relevant Families​

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

Producer Readiness Checklist​

  1. Producer preserves stable entity identity across contract change.
  2. Canonical change shape does not silently switch from reference-heavy to snapshot-heavy without compatibility review.
  3. Producer documents ordering assumptions and causation behavior.
  4. Replay of historical intake/canonical events is evaluated before emission.
  5. Change does not silently widen downstream blast radius into offer/publication consumers.
  6. Quarantine/DLQ implications are known for malformed or partially governed output.
  7. Producer observability still allows tracing source record to canonical change outcome.

RU-3 Offer And Publication​

Relevant Families​

  • offer-publication
  • projection rebuild jobs/signals

Producer Readiness Checklist​

  1. Producer preserves semantics of publication_state, integrity_state and freshness_state.
  2. New suppression or gating codes are not emitted without bounded downstream interpretation plan.
  3. Producer does not leak hidden governance internals into bounded publication contract.
  4. Replay of publication events is evaluated for stale visibility and duplicate projection risk.
  5. Producer defines how external surfaces should behave during overlap of old and new payload semantics.
  6. Failure modes are observable before and after cutover.
  7. Publication change is reviewed against offer-integrity and external webhook projection discipline.

RU-4 Commercial And Quote​

Relevant Families​

  • quote-lifecycle

Producer Readiness Checklist​

  1. Producer preserves strict distinction between indicative context and quoted promise.
  2. New fields do not silently weaken invalidation or expiry meaning.
  3. Repricing reason classes keep stable semantics or trigger version change.
  4. Replay of quote events is reviewed for booking guard, UI drift and webhook projection effects.
  5. Producer confirms how quote state changes map to external bounded notifications.
  6. Contract evolution does not create ambiguous commercial truth during version overlap.
  7. Observability keeps quote lineage, version and invalidation cause visible.

RU-5 Booking Commit​

Relevant Families​

  • booking-transitions

Producer Readiness Checklist​

  1. Producer preserves distinction between confirmed, pending and uncertain external states.
  2. New optional fields do not imply new success semantics by accident.
  3. Recovery-job emissions remain distinct from domain booking transitions.
  4. Replay of booking events is reviewed for support, settlement and webhook consequences.
  5. Producer defines incident-grade handling for mismatch between emitted event and transactional truth.
  6. Version overlap does not create conflicting booking narratives for downstream consumers.
  7. External booking-status projections remain bounded and support-safe.

RU-6 Post-Booking And Clearing​

Relevant Families​

  • post-booking-case
  • settlement-reconciliation

Producer Readiness Checklist​

  1. Producer preserves distinction between service-case truth and financial truth.
  2. New fields do not silently change discrepancy or clearing meaning.
  3. Duplicate-sensitive financial emissions are reviewed against retry/DLQ policy before release.
  4. Replay of settlement-related families has explicit finance-safe stance.
  5. Producer defines which events may project to external notification and which must remain internal.
  6. Failure and mismatch signals are visible to finance/ops contours.
  7. Version change does not create silent divergence between booking narrative and financial narrative.

RU-7 Controlled External Surface​

Relevant Families​

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

Producer Readiness Checklist​

  1. Producer preserves bounded semantics of governance_state and enforcement_class.
  2. New governance codes do not accidentally widen permissive behavior.
  3. Tenant-aware and partner-aware policy impact is reviewed before emission.
  4. Producer confirms whether change affects webhook compatibility or pull-reconciliation behavior.
  5. Version overlap is documented for external-surface operators and partner migration path.
  6. Observability reveals contradictions between enforcement decision and emitted signal.
  7. Producer does not leak internal enforcement matrix details into external-facing contracts.

Cross-Cutting Semantic Drift Checklist​

Для любого release unit change producer обязан подтвердить:

  1. Did any existing field keep the same name but change meaning?
  2. Did any bounded code gain a new interpretation that old consumers may misread?
  3. Did any reference-heavy payload become snapshot-heavy or vice versa?
  4. Did event ordering or causation assumptions change?
  5. If yes, is this still truly additive?

Cross-Cutting Replay Checklist​

Для любого release unit change producer обязан подтвердить:

  1. Can historical replay produce different downstream truth after the change?
  2. Which consumers and projections must be revalidated before replay is allowed?
  3. Are replay flows distinguishable from live flows in observability?
  4. Is finance/support/operator review required for replay of this family?
  5. Can replay accidentally trigger external webhook duplication or contradiction?

Cross-Cutting External Projection Checklist​

Если family участвует во внешнем async surface, producer обязан подтвердить:

  1. Does internal change alter external projection semantics?
  2. Does webhook payload remain bounded and partner-comprehensible?
  3. Are retry/redelivery expectations still valid?
  4. Can old and new projection versions coexist safely?
  5. Is partner-visible pull reconciliation still sufficient after the change?

Release Gate Use​

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

  • schema-family change;
  • event_version bump;
  • new bounded code introduction in critical families;
  • semantic reinterpretation risk of existing fields;
  • producer logic change on replay-sensitive family;
  • change that affects external async projection.

What Must Stay Out Of Scope​

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

  • превращать checklist в low-level implementation task list;
  • описывать broker-specific deployment mechanics;
  • считать, что producer can self-certify without consumer and external-boundary review.

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

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

Этот документ замыкает producer-side discipline и делает async contract evolution заметно более пригодной для industrial release governance.

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

Producer readiness для async contract changes должна включать:

Каноничные источники структур событий — в специализированных reference-документах фаз 4–6.

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