We shipped a perfect cache that zero real users could hit

During the July latency arc we put a stale-while-revalidate cache in front of the whole vibe HTML serve: first hit renders and stores, later hits return in milliseconds while a background refresh keeps the entry warm. We validated it end to end on prod — miss, then stale-refresh, then hit-fresh, TTFB dropping from seconds to ~230ms. Green lights everywhere. We moved on.

Then we profiled a real page load and found every actual visitor still paying the full 4–6 second synchronous render. The cache wasn't broken. It was undefeated and unemployed: it had simply never seen a real request (#3248).

Green on the URL nobody visits

The URL we benchmarked was the canonical one: https://public-feed--jchris.prod-v2.vibesdiy.net/. Clean, obvious, and — it turns out — requested by approximately no one. Real vibe views go through the viewer wrapper page, whose server-rendered iframe pins a query param onto every src:

texthttps://public-feed--jchris.prod-v2.vibesdiy.net/?npmUrl=https%3A%2F%2Fprod-v2.vibesdiy.net%2Fvibe-pkg%2F%3Fv%3D09acb00…

That npmUrl tells the vibe which package workspace to load its modules from, stamped with the current deploy version. The wrapper adds it to every iframe src, on every view, for every visitor.

Curl the bare URL: x-vibes-cache: hit-fresh, 230ms. Curl the URL with the param — copied out of the served wrapper HTML, not typed from memory — and the header isn't miss or bypass. It's absent. No cache participation at all, 3.9–5.8s TTFB across runs, once 10s in-browser. In the page's network waterfall, that iframe document request was the single dominant cost of the entire load.

The edge case that swallowed the 100% case

npmUrl exists for a genuinely personalizing feature: you can point a vibe at a custom npm workspace, and the server remembers your choice in a cookie. HTML rendered for your custom repo must never be served to anyone else. So when the cache was built, both of its ends treated the param as radioactive:

• The eligibility gate in swr-html-cache-orchestrator.ts only admitted requests with no query string.
• The render side in render-vibe.ts withheld its cacheable marker from any URL-captured npmUrl — and set a cookie on those responses, which makes them unstorable anyway.

Each gate was correct for the feature it protected. Together they classified the platform's own deploy stamp — present on 100% of production requests — as a personal preference. The safe default didn't fail loudly on the common case; it quietly declared the common case out of scope. Nothing in the plumbing distinguishes "we chose not to cache this" from "this request shape never occurs," so every dashboard we had said the cache was working. It was — for a request shape that exists only in benchmarks.

The platform's own pin isn't personalization

The fix (PR #3251) is a definition, not a loosening. A new predicate, isPlatformWorkspaceNpmUrl, answers one question: is this value the platform's own package workspace? It must match the worker's configured workspace origin and path exactly — only the ?v= deploy stamp may differ. Custom repos, malformed values, different hosts: all keep today's bypass.

With that predicate in hand:

• The cache admits exactly one query param, npmUrl, only when platform-shaped — and keys the entry by its re-canonicalized value, so HTML rendered for different deploy stamps never shares a cache slot. The version pin isn't noise to strip or personalization to fear: it's part of the cache key.
• The render side keeps its cacheable marker for platform-shaped values and skips the cookie for them — the wrapper re-sends the param on every iframe src, so the cookie was redundant in this flow, and dropping it makes the response storable.
• Cardinality stays boring: one entry per vibe, per wrapper deploy, per edge location. The first hit after a deploy pays the render — exactly what every hit paid before.

While we were in there, the wrapper document itself — the vibes.diy/vibe/… page that hosts the iframe — got the same SWR treatment in swr-wrapper-html-cache.ts, shaving roughly another half second of anonymous-view SSR per the PR's validation notes, with the same lifecycle, the same observability header, and the same rollback lever.

Benchmark the request production actually makes

This is the second post in a row where the decisive move was refusing to trust the canonical version of reality — last time a CDN was silently eating a header, and only curl against the deployed host told the truth. Same lesson, one layer up: the URL you test is a claim about what production requests look like, and that claim needs evidence. Copy the request out of the served HTML, the har file, the access log — anywhere real — before you call a cache shipped.

And when you write an eligibility gate, ask what percentage of live traffic each branch will actually take. A gate written to protect an edge case will happily classify everything as the edge case, forever, without an error, a log line, or a red dashboard. Ours needed one bit of humility: the platform stamping its own version onto a URL isn't a user expressing a preference. If your infrastructure's fingerprints disqualify requests from your infrastructure's cache, the only traffic you can serve fast is traffic that doesn't exist.