Caching & Build Optimization

## A cache key is a content-addressing problem A cache entry is a promise: *if the key matches, the stored bytes are the bytes this job would have produced.* The whole discipline follows from taking that promise literally. The key must be a function of every input that determines the content, and of nothing else. Anything determinant left out of the key produces wrong hits; anything non-determinant folded into the key produces missed hits. So the design question is not "what string do I put here" but "what actually determines what ends up in this directory?" ## What belongs in the key For a dependency cache, the usual answer is four things: 1. **A purpose prefix and a manual version.** Something like `deps-v3-`. The version digit is your escape hatch: when you discover an entry is bad, you bump it and the whole namespace rotates. 2. **A digest of the dependency manifest that pins versions** — `package-lock.json`, `pnpm-lock.yaml`, `poetry.lock`, `go.sum`, `Gemfile.lock`, `Cargo.lock`. Hash the *lock* file, not the loose manifest, because the loose one can say `^1.2` and resolve differently on two days. 3. **The toolchain identity.** The Node, Python, Go, JDK or compiler version. Wheels, native modules and compiled extensions differ between them, and this is the single most commonly forgotten component. 4. **The platform.** OS and CPU architecture, because a cache written on x86 Linux is not valid on arm64 or on a different libc. ```bash # key derived from every input that determines the content KEY="deps-v3-$(uname -s)-$(uname -m)-node$(node -v)-$(sha256sum pnpm-lock.yaml | cut -d' ' -f1)" ``` What does *not* belong: the branch name, the commit SHA, the run number, the date. None of them determine the content, and each of them guarantees a miss. ## Failure one — the key that never hits Symptoms: cache steps report a miss on every run; run times never improve; the cache store grows until eviction starts thrashing and even the legitimately reusable entries disappear. Causes are almost always over-specification — a commit SHA or timestamp in the key — or a digest computed over a file that changes on every run, such as a generated lockfile or a manifest the build itself rewrites. This failure is *loud in the metrics and silent in the logs*: nothing is broken, you are just paying full price. It is worth watching cache hit rate as an actual pipeline metric, because otherwise nobody notices for months. ## Failure two — the key that hits when it should not Symptoms: builds succeed, and ship the wrong thing. A job upgrades its runtime version but the key is only the lockfile digest, so it restores dependencies compiled against the old runtime. A cached build output is restored although a source file that fed it is not in the key, so a change never takes effect and the tests validate the previous revision. A native module cached on one OS image is restored on the next image generation. This is the dangerous one, because there is no signal. The pipeline is green, the diff looks right, and the artifact is wrong. Everything about key design is really about buying insurance against this case, which is why the correct instinct when in doubt is to add a component to the key: a wasted cache is a cost, a wrong cache is an incident. ## Partial and fallback restores widen the second failure Most platforms let you fall back to a related entry when the exact key misses — typically the newest entry whose key starts with a given prefix. This is genuinely useful: on a lockfile change you would rather start from last week's dependency store and download the delta than from nothing. But understand what you have accepted. A fallback restore is, by construction, content that does **not** match your inputs. It is only safe when the step that follows reconciles the restored content against the manifest — an installer that will still fetch what is missing and prune what should not be there. Never use a fallback restore for a cache of *build outputs*, where nothing downstream re-checks the content. ## Immutability and rotation On platforms where an entry is written once per key and never overwritten, a poisoned or stale entry persists until it is evicted — re-running the job does not fix it. That is exactly what the manual version prefix is for: changing the key is the only reliable way to abandon bad content. Design the key with that lever in it from the start, rather than discovering you need it during an incident. ## Verifying the design Two cheap checks. First, change one input at a time — bump the runtime version, touch the lockfile — and confirm the key changes each time; if it does not, you have found a wrong-hit path. Second, run periodically with caching disabled and compare outputs; a difference means an input is escaping the key.