What a cache key is really claiming

2026-08-15T12:00:00Z

A cache key is a promise, and it is worth reading it as one. It says: any two requests that hash to this string will accept the same answer. Everything that goes wrong with caching goes wrong because that promise was made carelessly.

The key is the dependency list

Write out what a cached value was computed from — every input, every flag, every piece of ambient state the code read without mentioning it — and you have written the key. If the list is complete, the key is correct by construction. If something is missing, you have not built a cache, you have built a way of serving one user's answer to another.

That reframing is most of the work. It turns an invalidation problem, which is about time and is therefore hard, into a naming problem, which is about being honest and is merely tedious.

Invalidation is a question about everything the cached answer was derived from, and about which of those inputs can change without anyone announcing it.

What that looks like here

The generator that built this page keys a rendered page on its own bytes, the config, the theme, and the set of icon files the capsule ships. That last one is not obvious, and it was not there at first: adding a favicon changes the head of every page, so a key that ignored it would serve pages from before the favicon existed, forever, with no way to notice.

Nothing in that key is a timestamp. A modification time answers a question nobody asked — it says when a file was touched, not whether what it says is still true — and a fresh checkout rewrites every one of them without changing a byte of content.

The failure mode is the interesting part

An under-specified key does not crash. It serves a wrong answer at full speed, with no error and no log line, and it keeps doing it until somebody notices by eye. That is why the honest move is to make the key say too much rather than too little: an over-specified key costs you a cache miss, which shows up in a graph, and an under-specified one costs you correctness, which does not.

Back to the posts

Writing under seven line types

2026-07-02T12:00:00Z

Gemtext has seven kinds of line and no inline markup at all. No bold, no italic, no link inside a sentence, no footnote. After a few weeks of writing under that constraint the surprise is not what it costs. It is what it removes the temptation to do.

Emphasis has to be earned

With no way to set a word in bold, stress has to come from word order and from what you choose to say. A sentence that needs a bold word to land is usually a sentence that has not decided what it is about. The format will not let you paper over that, so you rewrite it instead.

The same goes for the aside in parentheses that wants to be a footnote. There are no footnotes. Either the thought belongs in the paragraph or it belongs in a different paragraph, and deciding which is the writing.

A link is a whole line

This is the constraint with the widest blast radius. A link cannot sit inside a sentence, so every link stands alone with its own label — which means every label has to make sense read aloud, out of context, by somebody who cannot see what surrounds it.

That is exactly what accessibility guidelines ask of link text at their strictest level, arrived at here by accident rather than by effort. The format made the rule unavoidable before anyone thought to argue for it.

Links arrive in runs, so a run of them is a list, and a reader can be told how many there are
Every target clears a large touch area without any inline exception
Nothing depends on seeing a typeface change

What it is bad at

It would be dishonest to only list the wins. Gemtext cannot quote its own syntax — a preformatted block is closed by the first fence inside it, so the one thing this page cannot show you is a fence. Tables do not exist. Anything with two axes has to become prose or a picture.

And the format has no place to put metadata, which is why the date on this post lives in the link line that points at it rather than in the file you are reading.