Skip to main content

Migration State Authority and Uncertain Writes

What This Concept Is​

A migration has both interface compatibility and state compatibility obligations. During coexistence, old and new callers must agree on the authoritative state or follow an explicitly defined synchronization model. Traffic routing alone is not a data migration.

Why It Matters Here​

Two independent stores can pass separate old-only and new-only tests while failing mixed clients. A successful new write may also make rollback to old code unsafe if its data format or side effects cannot be understood or reversed.

Concrete Example​

An old Grid client writes A at (0,0). A new client must read A through get_at((0,0)). If each API writes its own map, that observation fails. Delegating both interfaces to one store preserves this sequential exercise; a real multi-store migration needs additional machinery.

Now a selected provider records a message and raises TimeoutError because the acknowledgement was lost. Calling another provider can duplicate delivery. The lab sends once and propagates uncertainty. It does not promise global exactly-once delivery.

Common Confusion / Misconception​

Adding an idempotency-key parameter is insufficient. Its scope, retention, payload conflict rules and durable shared deduplication semantics must exist at the authority that commits the effect. A process-local dictionary cannot establish recovery across process loss or independent providers.

How To Use It​

Inventory client versions and stored formats. Define state authority, backfill and reconciliation obligations. Exercise mixed calls and failures after writes. Separate routing rollback, data recovery and business compensation. Document a stopping rule and a roll-forward path where reversal is unavailable.

Check Yourself​

Why is a timeout different from a rejected request? When can the compatibility alias be removed?

Mini Drill or Application​

Run the grid and provider labs. Then propose a migration to a second persisted store. Name an interleaving, an acknowledgement-loss case and an observation required before retirement. Feedback: the in-memory checks do not establish backfill completeness, concurrent cutover or durable deduplication.

Read This Only If Stuck​

Use the Refactoring book index for small-step discipline and the reading guide for supporting primary documentation. Continue with the contracts and labs.