How to Prove Functional Equivalence

Part 2 built the instrument. Shadow traffic mirrors real production requests to the modernized slice, compares the output against the legacy system, and hands you a stream of divergences — concrete, reproducible differences for the same real input. That stream is data, not yet a verdict. This part is about the verdict: how you turn a pile of divergences into a defensible claim that the slice is functionally equivalent to the system it replaces.

What “functionally equivalent” has to mean

Functional equivalence is a claim about observable behavior: for the inputs that matter, the modernized slice produces the same outputs and the same state effects as the legacy system. It is deliberately not a claim about internal implementation. The new slice may use a different algorithm, a different data model, a different language entirely — none of that matters if what the system does, as seen from outside, is the same.

That framing keeps the goal honest in two directions. It rules out the false comfort of “the code looks right” — implementation review is not equivalence. And it rules out the false demand of “every byte must match” — internal representation that never surfaces is out of scope. The bar is behavior the rest of the world can observe: API responses, persisted state, emitted events, downstream calls.

Equivalence is a claim you defend, not a number you hit. The work is making sure every difference has an answer.

The triage: three buckets for every divergence

Every divergence that survives Part 2’s normalization gets sorted into exactly one of three buckets. This classification is the work of proving equivalence.

1. Real defect — the new slice is wrong. The legacy output is correct; the modern slice produced something different and worse. A rounding rule implemented differently, an edge case dropped, an off-by-one in pagination. These are bugs. They go to the team, get fixed, and the fix is re-validated against the same shadowed input that caught it.

2. Intended change — the new slice is correct by design. The outputs differ because you meant them to. Part 1’s honest boundary lives here: a known legacy bug you’re fixing, a workflow you’re improving, a deprecated behavior you’re retiring. The legacy output is the “wrong” one. These divergences are expected, and the proof obligation flips: you show the new output matches the new specification, not the old behavior.

3. Benign noise — neither is wrong. A difference with no observable consequence: an unordered list in a different order, a timestamp, formatting. Ideally Part 2’s normalization already absorbed these. When a new species of noise appears, the response is not to wave it through — it’s to write a normalization rule, review it, and re-run. A masked field is a field you’ve stopped checking, so each mask is a deliberate, recorded decision.

The discipline is that there is no fourth bucket. “We’re not sure what that one is” is not a resting state — it’s an open item. Every divergence is either explained or unexplained, and an unexplained divergence blocks promotion no matter how rare. That’s the whole game: not zero differences, but zero unexplained differences.

Bucket	Who’s right	Action	Effect on promotion
Real defect	Legacy	Fix the slice, re-validate	Blocks until fixed
Intended change	Modern (by spec)	Document, exclude from parity bar	Allowed, recorded
Benign noise	Neither	Add normalization rule, re-run	Cleared once rule reviewed
Unexplained	Unknown	Investigate — never assume	Blocks until classified

Driving the rate down — and what the rate isn’t

As defects get fixed and noise gets normalized, the unexplained-divergence rate falls. Watching that curve flatten toward a defensible floor is how you know the slice is converging. But the rate is a thermometer, not the patient. Two failure modes hide inside a good-looking number:

• A low rate over thin traffic. Ninety-nine percent match across a week that never hit month-end is a number about the easy paths. (Part 2’s lesson: match the window to the system’s real cycles.)
• A low rate achieved by over-masking. You can drive any divergence rate to zero by normalizing aggressively enough. That’s not equivalence; it’s hiding the evidence. The integrity of the rate depends entirely on the integrity of the exclusions behind it.

So the number is reported alongside its context: what traffic it covers, what windows it’s seen, and every normalization rule it depends on. A reviewer who can’t see the exclusions can’t trust the rate.

The paths production never sends you

Shadow traffic is only as complete as production is representative. It will faithfully exercise the common 95% of behavior and may never once trigger the error branch that fires when an upstream times out, the quarter-end reconciliation job, or the handling of an input format no client has sent in two years. Those paths are often exactly where legacy systems hide their most load-bearing quirks.

You cannot wait for production to maybe send them. You go get them:

• Historical replay. Pull real past requests from logs or archives — including the rare and the malformed — and replay them against both systems offline. This is shadow traffic’s logic applied to recorded inputs, and it’s how you reach the cases that are rare but real.
• Synthetic edge cases. For paths with no recorded example (a failure mode that’s never occurred, a new error condition), construct inputs deliberately and assert the new slice’s behavior against the documented intent.
• Coverage accounting. Maintain an explicit list of known rare paths and their status — covered by replay, covered by synthetic test, or still open. “Equivalent over observed traffic, with these rare paths covered and these still open” is a claim a reviewer can weigh. “Equivalent” with no coverage statement is not.

Equivalence is not correctness

A boundary worth stating plainly, because it’s easy to oversell: proving functional equivalence proves the modern slice matches the legacy system. It does not prove the legacy system was right.

If the old system has computed a tax the wrong way for a decade, a perfectly equivalent slice will compute it the same wrong way. Equivalence faithfully preserves behavior — including behavior you’d be horrified to learn about. That’s the correct default for a migration: change the implementation, hold the behavior, so the cutover is safe and reversible. But it means equivalence testing is a migration safety tool, not a correctness audit. When the discovery phase does surface a behavior that looks wrong, that’s not an equivalence question — it’s a requirements decision: replicate it, or move it to bucket two and fix it on purpose. Don’t let a clean equivalence report be mistaken for a clean bill of health on the legacy logic.

What a defensible equivalence claim looks like

Pulling it together, the artifact that lets a stakeholder sign off on promoting a slice reads roughly like this:

• Over N of real shadowed traffic across these cycles (including the load-bearing ones), the unexplained-divergence rate is at a defensible floor.
• Every real defect found has been fixed and re-validated against the input that caught it.
• Every intended change is documented and validated against the new spec.
• Every normalization rule is listed and reviewed; nothing material is masked.
• These known rare paths are covered by replay or synthetic test; these remain open and are accepted risks with a named owner.

That is functional equivalence testing: not a promise that the systems are identical, but a written, reviewable account of every way they differ and why each difference is acceptable.

Where this leads

This part treated divergences as units to triage. But finding them — comparing two complex outputs and reconciling two evolving datastores — is its own discipline, full of traps that quietly corrupt the evidence. Part 4, Reconciliation & Output Comparison, goes deep on the comparison machinery: structural diffing, tolerance rules, and how you reconcile state when legacy and modern are both writing — the data-heavy core of getting equivalence right.