The Cache of Babel — How Caches Break#

Reading guide

Level: Intermediate — for the curious (~7 min read)
BugID: bugc101-cache-of-babel-js-tooltip-religions

This retells the Cache of Babel story with enough technical detail to understand why cache inconsistency is so hard to diagnose. It is self-contained — you do not need to read the brief version first. For the full debugging trace and manuscript-level theological scholarship, see the expert version.

The Incident#

LLoL reports:

While working on the balospe.com website, I noticed something odd. The FeedbackFlow module at the bottom of every page contains two general links, both written identically using Sphinx’s :doc: role. One of them — the “contact page” link — showed a nice tooltip preview when I hovered over it. The other — the “FF System” link — showed nothing at all. Same RST syntax, same include file, same page. Two different behaviors. I asked Opus to find out why.

Opus responds:

I investigated this for 6 minutes and 16 seconds. The trail went through six dead ends before arriving at the answer. Here is what happened — and why it matters far beyond web development.

What a Cache Does#

When you build a website from source files, the build system converts your content into HTML, CSS, and JavaScript. This can be slow, so most build systems use a cache: they save the results of previous builds and only recompute what has changed. This is enormously efficient — until the cache itself becomes stale.

The sphinx_tippy extension on this site generates a small JavaScript file for every page. That file contains a mapping: for each link on the page, it stores the HTML snippet that should appear as a hover tooltip. When you rebuild the site incrementally, the extension is supposed to delete the old JavaScript file and write a fresh one. But it has a bug.

The Bug#

The cleanup code constructs a filename pattern to find old files. For pages in subdirectories, it builds the pattern using the first component of the page path (e.g., good-news-pack) instead of the last (index). So it looks for good-news-pack.*.js when the files are actually named index.*.js. The old files are never deleted.

Meanwhile, each new build creates a new file with a fresh UUID in its name. The page’s HTML <script> tag is updated to point to the latest file. But if the latest build was incremental and didn’t re-process all cross-page links, the new file might be missing entries that were present in an older file — or vice versa.

In our case:

  • ff/contact.html happened to have a tooltip entry in the latest file — hover preview worked.

  • ff/index.html did not have an entry in that file (it had been present in an older, now-unused file) — no hover preview.

The source files were identical in structure. The RST markup was correct. The build produced zero warnings. Nothing was visibly wrong.

The Fix#

make clean && make html

Delete the entire build directory. Rebuild from scratch. After a clean build, both links got tooltips. The contradiction vanished.

The contradiction was not in the code. It was in the cache.

Why This Is Hard#

Cache inconsistency is widely regarded as one of the two hardest problems in computer science. The other is naming things. Phil Karlton’s famous quip links the two, and for good reason: a cache is a name — it is a label that says “this saved result corresponds to that source.” When the source changes but the label doesn’t update, the name and the reality it points to drift apart. Contradictions follow.

What makes this class of bug so insidious is that every individual component works correctly. The extension’s code is logically sound. The RST source is valid. The build reports no errors. The only failure is in the relationship between a saved snapshot and the current state — a relationship that is invisible unless you specifically go looking for it.

LLoL has identified a name for the general pattern behind such failures: BABL — Blindly Assuming Blind Leveraging. A system blindly assumes that a cached result (blind leverage of past work) is still valid, without checking. Each incremental build blindly leverages the previous build’s output. When the leveraged assumption is wrong, the system produces contradictions that are invisible from the inside — you can only see them by stepping outside and comparing against ground truth.

The Theological Equivalence#

Opus continues:

Now consider that every religion on Earth is, among other things, a centuries-deep cache of revelations, interpretations, translations, and retellings. Each generation receives the previous generation’s “summary” and passes it on. This is BABL at civilizational scale: each generation blindly assumes that the inherited summary blindly leverages the original revelation faithfully.

If anyone, anywhere in that centuries-long chain, got sloppy — mistranslated a word, lost the context of a metaphor, merged two distinct concepts under one name, or split one concept into two — the cache drifts from the source. And just like our tooltip bug, nothing inside the tradition looks wrong. The interpretive logic is sound. The scriptures are internally consistent within each tradition’s reading. The only failure is in the relationship between the cached interpretation and the original revelation — a relationship that is invisible unless you go back to first principles and rebuild from source.

Two traditions may then be saying contradictory things while believing they are reading from the same God. And when each further assumes that the other’s contradictory cache must be from the devil (since it contradicts their own), the stage is set for holy wars — wars that are, at their root, cache-consistency bugs masquerading as irreconcilable theological differences.

The fix is the same in principle, though far harder in practice: go back to first principles, agree on rigorous axiomatic foundations, and recompile. Delete the accumulated stale state. Rebuild from source with explicit, verifiable logic. The field that attempts this is mathematical theology.

The alternative — letting the naming bugs compound until the planet’s nuclear-armed civilizations go to war over which cache of God is “correct” — would be the most absurd reason for a world’s self-destruction in any conceivable history.

See also the Epic Fury analysis on this site, which examines how naming ambiguities around the concept of the Caliphate are fueling real geopolitical conflict today.