"Trust me, it works" is not a migration plan: what a real parity harness looks like

# "Trust me, it works" is not a migration plan: what a real parity harness looks like Every infrastructure migration eventually reaches the same moment: the old system and the new system are both built, and someone has to decide whether it's safe to cut over. Most teams answer that question with a demo and a gut check. That's not proof — it's intuition dressed up as confidence. ## The situation In one system we worked on, file storage was bound to a proprietary platform's own sidecar — no CLI, no filesystem mount, no bulk export path. Migrating off it meant two separate problems: getting the data out, and proving the replacement produced identical results once it was in. Getting the data out meant reusing the application's own storage client from inside its running environment to enumerate and pull every object — no external export tool existed. **Proving the replacement worked** meant something more specific than "the new code runs without errors." ## Why "the tests pass" isn't the bar A new storage backend can pass every unit test and still silently corrupt the thing that actually matters: whether real outputs, computed from real inputs, come out the same as they did before. Metadata formats differ between platforms. Presigned URL generation differs. ACL semantics differ. Any one of these can be subtly wrong in a way that a green test suite won't catch, because the suite was written against the *new* system's own assumptions of correctness. The only way to know the new system actually replicates the old one is to run them both against the same real inputs and diff the actual output. ## What a parity harness actually is A parity harness is a regression test with one job: run the old path and the new path on identical real inputs and compare the results byte-for-byte. Not "close enough." Not "passes the same assertions." The actual output, diffed. In this case: pick a representative sample of real records that exercise the system end to end — not synthetic fixtures, actual production-shaped data — run the full computation through both the old storage backend and the new one, and compare every byte of the result. The result across the sample: **byte-identical output, every time.** Not approximately similar. Not "the differences look benign." Identical. ## Why that's a categorically different claim than "it works" "It works" is a claim about the present — the demo ran, nothing crashed. "Byte-identical parity across a representative sample" is a claim about correctness that anyone can independently re-verify: run the harness again, get the same diff, done. It doesn't rely on trusting the person who built the migration. It's evidence, not testimony. That distinction matters most exactly when the person deciding whether to cut over isn't the person who can read the code — a non-technical founder, an ops lead, a board. They can't audit the migration line by line. But they can ask one question: "did you diff the actual output against the old system, and did it match?" A parity harness is what makes the honest answer to that question "yes, byte for byte," instead of "we're pretty confident." ## The broader lesson If a migration touches anything that produces output someone downstream relies on — a report, a computed value, a rendered document — "the new code deploys cleanly" is not the bar. Build the diff. Run both paths on real data. Compare the actual bytes. Anything short of that is asking someone to take your word for it — and due diligence exists precisely because that isn't a standard anyone can verify.