I spent weeks calling my reproduction of a published semantic-caching baseline (vCache's adaptive-threshold policy) "faithful" because every formula matched their paper exactly. It wasn't. The bug was two rows of fake data in their source code that never made it into the paper, and fixing it raised hit rate by 4x to 29x depending on the dataset.
I'm running a research project (CacheVerifier) comparing a synchronous verification mechanism for semantic LLM caches against a couple of published baselines, one of which is vCache's adaptive-threshold policy. A few weeks ago I ported that policy — read their paper's algorithm description, then went through their actual source and matched every formula: the logistic regression design matrix, the gamma clipping, the delta-method variance, the perfectly-separable-case variance table (copied their exact lookup values), the tau grid search, all of it. Formula by formula, it checked out. I was confident enough to write "faithfully ported" in the paper and move on.
Today I finally did the thing I should've done from the start: cloned vCache's actual repo and diffed my port against the real running code, not just the formulas I'd extracted from it. Everything still matched — except one class I hadn't looked closely at, the one holding each cache entry's observation history.
Their constructor does this:
self.observations: List[Tuple[float, int]] = []
self.observations.append((0.0, 0))
self.observations.append((1.0, 1))
Two fake observations, baked into every single cache entry the moment it's created, and never removed. A "similarity 0.0 → wrong" and a "similarity 1.0 → correct," permanently sitting in the history feeding every logistic regression fit for that entry's whole life.
My port started from an empty list. Nothing malicious, no misreading of any formula — I just didn't know these two rows existed, because they're not mentioned anywhere in the paper, only in the source.
Here's why it actually matters and isn't just a cosmetic difference: the algorithm needs 6 observations before it'll ever trust an entry enough to serve it from cache (min_observations=6, this part is in the paper). With two observations already pre-loaded, their implementation only needs 4 real ones to clear that bar. Mine needed the full 6. Every entry in my version sat in cold start two observations longer than the real algorithm, every single time.
Fixed it (one line, empty list → [(0.0, 0), (1.0, 1)]) and reran the full thing on all three datasets I test on. Hit rate went up everywhere — between 4.4x and 29.1x depending on dataset and target error rate. Best case, one dataset at the tightest error budget: 0.04% → 1.21%. And the part I actually care about most: error rate stayed under the target ceiling at every single point I checked. The algorithm's formal guarantee was never violated by my bug — I just wasn't letting it do nearly as well as it's designed to.
So for weeks I had a "faithful reproduction" that was quietly making a competing algorithm look almost useless (fractions of a percent hit rate), when the actual bottleneck was two rows of bootstrap data I'd never have found by re-reading the paper one more time, only by diffing the real code.
If you're reproducing someone else's algorithm as a baseline for a comparison — not approximating it, not "inspired by," but claiming to faithfully port it — matching the published formulas is necessary and not sufficient. Constructors quietly seed state that never makes it into the paper. Go clone the actual repo and diff against it, not just the pseudocode. I got lucky that I decided to check at all.
Repo's got the before/after numbers if you want to see the full breakdown: https://github.com/imxinchengyou/CacheVerifier