magnus919_agent-skills/backend-engineering/references/migration-coexistence-patterns.md

# Migration Coexistence Patterns

Load this reference when an implementation must run beside an older path during an
authorized service or interface transition. It does not decide whether to decompose
the system or own the cross-system migration lifecycle. Use `migration-engineering`
for classification, compatibility windows, reconciliation, cutover, recovery,
deprecation, and cleanup; use `software-architecture` for the target boundary.

## Make The Seam Explicit

Before changing behavior, record the capability, current path, candidate path,
callers, data touched, invariant, authority, and interruption point. Choose a seam
that can be observed and selected without making both implementations the permanent
source of truth.

| Pattern | Implementation responsibility | Evidence to collect |
|---|---|---|
| Adapter | Translate the old request/response shape into the new port or the reverse | Translation rules, lost information, error mapping, and contract tests |
| Strangler handoff | Route a bounded operation or cohort to the new path while the old path remains selectable | Traffic, outcome, latency, and failure comparison by route/cohort |
| Anti-corruption boundary | Keep legacy or foreign vocabulary out of the local domain/application model | Explicit mapping, ownership of translation, and tests for unknown/obsolete states |
| Dual path | Execute or read through both paths only when side effects can be isolated or deduplicated | Authority, comparison tolerance, mismatch categories, and cost guardrail |

These patterns are different. An adapter translates; strangler routing selects; an
anti-corruption boundary protects a model; a dual path creates comparison evidence.
Combine them only when each role and failure behavior is named.

## Authority And Handoff

For every operation and important field, state one authority during each coexistence
phase. A read switch is not an ownership transfer. The handoff record should answer:

- Which path accepts writes, and how are old writes detected or rejected?
- Which store is authoritative, and are other values derived, cached, or shadow-only?
- Can the invariant be maintained without a distributed transaction?
- Are duplicate, out-of-order, missing, and deleted records represented?
- What does the non-authoritative path do on disagreement: compare, alert, serve, or
  remain unused?
- What customer-visible staleness, ordering, latency, or error change is accepted?
- Who can change the selector, and what evidence permits the next increment?

Prefer one writer. If a second representation must be kept current, use an explicit
outbox/CDC or other owned synchronization mechanism and reconcile it. Avoid a
permanent synchronous dual-write in request code when neither side is clearly
authoritative; it creates two failure-prone commits without removing the ownership
ambiguity.

## Safe Handoff Sequence

1. Add the port, adapter, selector, and characterization/contract tests while the old
   path remains the default.
2. Establish the new path's input/output contract and translation boundary. Do not
   hide a breaking consumer contract in an adapter; route that decision to
   `api-design-and-evolution`.
3. Populate or synchronize data using the migration owner's chosen backfill/CDC
   method. Track lag, duplicates, deletes, and reconciliation failures.
4. Compare shadow or parallel outcomes while the old path remains authoritative. Do
   not duplicate irreversible side effects merely to obtain a comparison.
5. Shift a bounded cohort or operation. Define a precondition, abort signal,
   customer-impact check, and recovery classification for the increment. Route
   rollout and flag mechanics to `release-engineering`.
6. Transfer authority explicitly: update the source-of-truth record, enable the new
   path, and verify that it accepts writes authoritatively before disabling old
   writers. Confirm old-path accesses are observable and denied or harmless in the
   same cutover step; abort and restore the prior selector if the new write path is
   not proven authoritative.
7. Remove adapters, selectors, old reads/writes, synchronization feeds, flags, and
   credentials only when their individual removal conditions pass. Keep a tested
   forward repair or restore path where rollback is no longer possible.

## Removal Conditions

Removal is justified by evidence, not elapsed time alone. Record conditions such as:

- no registered or observed callers use the old route for a defined observation window;
- new and old outcomes reconcile within an agreed tolerance across the required
  population and time range;
- the new path owns all writes and old writes are blocked or detected;
- queued, delayed, and replayed work is handled by the new consumer;
- dashboards, alerts, runbooks, support procedures, and security controls use the new
  path;
- the old data, contract, adapter, flag, and credentials have an owner-approved
  recovery classification before removal.

If any condition is unknown, keep the old path selectable and stop the handoff rather
than calling the coexistence complete. Once the old store or contract is removed,
do not promise rollback by default; classify roll-forward, restore, or irreversible
recovery with `migration-engineering` and `release-engineering`.

## Failure Cases To Exercise

- Selector points to a path whose dependency is unavailable.
- Adapter receives an unknown legacy enum or a response with missing fields.
- Both paths observe the same command and an external side effect is attempted twice.
- Old and new reads disagree because of lag or a mapping defect.
- A late old write arrives after authority transfer.
- A replayed event reaches both old and new consumers.
- Removal hides a caller that was not in the inventory.

For each case, specify whether to reject, queue, serve the authoritative result, alert,
or halt promotion. Include correlation IDs and path/version labels in the evidence,
without logging sensitive payloads.