# Compatibility, Rollout, and Rollback

## Decision gate

Inspect observable contracts before implementation: APIs, SDKs, functions, CLI output, database semantics, messages, configuration, files, caches, telemetry, accepted input, timing, errors, and side effects. A unit, default, ACK timing, or failure-semantics change can be breaking even when structure is unchanged.

Do not create permanent dual implementations by default, but do not break public contracts silently. If the user has not chosen a strategy, explain affected callers, historical data, release constraints, maintenance cost, and rollback impact, then ask them to choose direct replacement or compatibility preservation.

Recommend from caller control, synchronized release ability, rollback boundaries, and compatibility cost. If the user already chose, proceed without asking again.

## Direct replacement

Update controlled callers, tests, docs, and configuration in scope. Do not retain indefinite compatibility code. State synchronization or downtime requirements and whether old versions can read newly written data.

## Preserve compatibility

Define whether compatibility covers structure, behavior, historical data, or mixed-version communication. Specify conflict precedence, compatibility tests, and an exit condition for temporary paths.

## Migration is separate

Data migration is independent from API compatibility. Define old and new states, transformation, cutover, validation, rollback or forward-fix boundary, transitional reads or writes, idempotency, difference detection, and cleanup conditions.

Do not defer a user-selected migration merely by calling it a later phase unless the user narrows scope.

## Mixed versions and rollback

Test old producer to new consumer, new producer to old consumer, old service to new data, and new service to old data as applicable. If mixed versions are unsupported, require atomic deployment or downtime explicitly.

Separate code, configuration, traffic, and data rollback. If new side effects or data cannot be reversed safely, define forward repair, monitoring, and stop conditions instead of claiming rollback support.