Reversal Window

A platform team agrees in March that the new tenant identifier will be a sequential integer, which is then a one-line change. By November it appears in 40 million stored rows, in bookmarked URLs, in two partners' reconciliation files and in the alert that pages on-call when the number stops advancing. Reversing it is now a programme of roughly 270 days, most of it spent waiting on other people's release calendars.

Nothing about the decision changed. What changed is how many parties had copied its shape into places the team does not control. Labelling decisions reversible or irreversible treats reversibility as fixed at decision time. It is a quantity that decays at a rate set by that copying, so the label assigned on day one is wrong by the time anyone consults it.

Why it matters

Deliberation is rationed by this judgement, and the standard advice - spend analysis in proportion to irreversibility - is routinely applied to the wrong axis, because teams estimate irreversibility from the invoice value of the component. A team will spend three weeks choosing a database that sits behind one repository interface, and ten minutes on an identifier format that ends up in 400 other codebases. The ten-minute decision was the permanent one.

Knowing the window decays also changes when you act: a choice you suspect is wrong is worth reversing now rather than next quarter, because the reversal is cheapest today.

Implementation patterns

• Count the copiers, not the cost. Ask how many parties will hold a copy of this choice's shape - zero, one team, every team, every customer - and let that number set the analysis budget.
• Put the indirection where the carriers are. A mapping layer between external and internal names keeps a published contract reversible, because a rename becomes a mapping change. An abstraction over a database's API does not keep the data reversible, which is where the cost sits.
• Version the data shape from the first row, and keep both implementations live during a swap, so the window stays open until the switch is proven rather than closing at the first write. A backfill you planned for is a job; a backfill you did not is a project.
• Record the closing date. "Reversible until external partners integrate, expected Q3" is actionable; "reversible" is not.

Industry example

Discord's 2023 move of its message store from Cassandra to ScyllaDB held a window open deliberately. The destination speaks the Cassandra protocol, so the data model and the client code survived the migration. A store with a different data model would have closed the window on every service that queried messages; this stayed a change of engine rather than of contract, which is why it could be executed and, if necessary, abandoned.

Failure scenarios

• A deprecation discovered from the outside. A rename ships, a customer's integration breaks, and the team learns its consumer count from a support queue.
• The reversible rewrite that was not. A new service writes rows in its own shape for six months; rolling back now means reconciling two schemas, so the rollback plan quietly expires.
• The abstraction that abstracted the wrong thing. A vendor-neutral layer hides the API and leaks the query planner's performance, the isolation semantics and the operational surface.
• Reversal refused by muscle memory. The rollback works technically, nobody remembers how to operate the old system, and it is vetoed mid-incident.

Trade-offs

Holding a window open buys cheap correction later and pays in indirection layers, versioned data and two implementations to run. Letting it close pays no premium and gives full use of the chosen technology's features, at the price of a correction measured in quarters and negotiated on other people's calendars. The premium is only worth paying where the window would otherwise close fast and the choice might be wrong.

When not to use it

Where there are no external consumers, retention is 30 days and one team is on call, almost every decision is reversible and this analysis is overhead: pick, ship, and keep the migration muscle warm. The concept earns its keep once a second party exists whose release calendar you would have to negotiate with. It is also the wrong frame where irreversibility is non-technical: a signed three-year contract has a window of zero regardless of the code.

Interview question

Q: Name two decisions your team made last year that looked small and turned out to be expensive to change, and two that looked momentous and turned out to be cheap. What distinguished them, and what would you do differently at the point of decision?

What a strong answer covers: the number of parties holding a copy of the choice's shape as the discriminator rather than technology cost; stored data and published contracts as the carriers that force calendar time; and the cheap intervention - a name-mapping layer, a versioned payload - that would have kept the window open.

Quick check

Quiz: A choice sits in a public API response used by 400 integrators under a 12-month deprecation policy. What is the minimum elapsed time to reverse it? About 12 months - the notice period runs before removal begins.

Flashcard: Which three accumulations close a reversal window, and which closes fastest? — Persisted data shape, published contracts, operational muscle memory; contracts close fastest, at the first external integration.