The Ship of Theseus Passes Its Integration Tests
Text
1. The claim
A strangler-fig migration proceeds route by route. Each move is small, reversible, and independently verified, which is why the pattern works and why it has largely replaced the big-bang rewrite. Nothing in this paper disputes that.
What the pattern does not produce is a point in time at which someone says: the system is now the new system, its guarantees are these, and this person owns them. In a big-bang cutover that moment is unavoidable and expensive, and its expense is what buys the verification. Incremental migration makes the moment optional, and optional organisational moments do not happen.
2. What decays in the gap
2.1. Invariants that were only ever end-to-end. Consider a property like “every accepted order appears in exactly one settlement batch”. In the old system that held because one process owned both sides. Route-level verification checks that the new order path matches the old order path and that the new settlement path matches the old settlement path. It does not check the property that spans them, because that property was never a route.
old system invariant held here [ orders -- settle ] <---- one owner, one processduring migration [ orders ] —> new each route verified [ settle ] —> old against its own old half ^ +— nobody verifies the span
after [ orders — settle ] invariant assumed, not checked
2.2. Ownership that never transfers. The old system has an owner. The new one has a migration team. When the last route moves, the migration team disbands and ownership arrives at whoever is nearest, usually by accident, usually discovered during the first incident.
2.3. The old path that never dies. A residual route left for a “long tail” client, a batch job, a reconciliation script. It has no owner and no decommissioning date. It accumulates the property of being the thing nobody understands, which is where 5.7 picks up.
2.4. The documentation describes neither system. During migration every document is provisional. Provisional documents are not maintained, and the migration is long enough that the habit of not maintaining them outlives it.
Figure 2. What incremental migration verifies well against what it leaves open. An impression rather than a finding; this is a draft, and the bars are part of what Section 6 is asking about.
3. Why “it is done when the last route moves” is not enough
Because the last route is chosen by difficulty, not by importance. Migrations move the easy traffic first, which means the final routes are the ones with the most unusual requirements and the least understood behaviour, and the project reaches its lowest morale and highest cost at exactly the point where the remaining work is hardest to verify. “Ninety percent migrated” is a statement about routes and almost never a statement about risk.
4. The proposal: identity by declaration
The remedy I am proposing, and the part I am least sure of, is to reintroduce the moment deliberately, without reintroducing the risky cutover that the pattern exists to avoid. It is a document and a date, not a deployment.
| § | Declaration |
|---|---|
| 1 | Name the spanning invariants at the start, before the first route moves, and build a check for each that runs against the live system throughout the migration rather than against either half. |
| 2 | Publish a route ledger: every route, its state, its verification, its owner. One page. It is the only honest answer to "how far along are we". |
| 3 | Declare a date on which the old guarantees end, and name the person to whom the new ones transfer. This is the moment. It costs a meeting. |
| 4 | Set the decommissioning date before the migration starts, with an owner, and treat slipping it as a decision that needs a reason rather than as a default. |
5. The strongest objection, unanswered
6. Open questions
Stated plainly, because this document is not finished and pretending otherwise would be the failure mode the rest of the site is about.
- Is the spanning-invariant decay measurable, and does it differ from the background rate in comparable systems that did not migrate?
- Does the declaration in Section 4 change behaviour, or does it become a ceremony that is performed and ignored?
- Is there a version of the route ledger that survives the migration and becomes the ownership document, or does it die with the project?
- Does this apply below some size? A four-route migration probably needs none of this, and I do not know where the threshold is.
7. What this paper does not claim
Big-bang rewrites are not better. They are worse, and the pattern this paper criticises is the correct default. Incremental migrations do not fail; most of the ones I have seen succeeded on their own terms.
The claim is only about what they leave behind, and at 0.55 it is a claim I would not want quoted without its confidence value attached to it.
Retirement conditions
This paper MUST be retracted if any of the following is demonstrated.
| § | Condition |
|---|---|
| 1 | A completed incremental migration of substantial size where no identity declaration was made, and where ownership, invariants and the decommissioning of the old path nonetheless resolved cleanly within a year of the last route moving. |
| 2 | Evidence that end-to-end invariants are preserved by route-level verification in practice, which would remove the specific decay this paper is worried about. |
| 3 | A demonstration that the residual old system is retired at similar rates whether or not a decommissioning date was declared in advance, which would make Section 4 ceremony. |
Revision history
| Date | Change |
|---|---|
| 2026-08-14 | Text written and published as a draft. The mechanism is stated, the evidence is thin, and the objection in Section 5 is unanswered. Open questions listed in Section 6 rather than hidden. Confidence unchanged. |
| 2026-08-09 | Listed in Section 5 with a title, a summary and a confidence value. No text. |