The difference is testable. An invariant is something that, if it stops being true, means the system is wrong even though nothing crashed. A preference is something that, if it stops being true, means somebody is annoyed.

an example, small enough to hold

A gallery site for a painter. The obvious requirements arrive first: pages for the works, an admin panel to add them, decent typography, a contact form.

None of those are invariants. These were:

• Withdrawing a work removes it everywhere at once: from the pages, the cache, the feed, etc.
• Publishing is all-or-nothing. There is no state in which half the new exhibition is live.
• The images outlive the site. If every line of code is deleted, the work is still on disk in its original resolution, in a directory a human can read.

Notice what those three do to the design before a single technology is named. The first rules out any cache the publishing step cannot invalidate synchronously. In practice that means the publishing step must own the cache rather than politely notify it. The second gives you the atomic swap. The third says the images are not allowed to live only inside a CMS's storage abstraction, which quietly disqualifies most CMSes.

Three sentences, and the shape of the system is already decided. The stack is now a consequence: static output, a build step that owns the whole output directory, images stored as files under names a person chose.

why this order and not the other

The reverse order, tools first, feels faster because tools are concrete and invariants are not. You can install a framework this afternoon. You cannot install a decision about what must never be untrue.

But the cost arrives later and is charged with interest. When you pick the tool first, you inherit its invariants, and its invariants were written for someone else's problem. Every requirement of yours that conflicts with one of them becomes a workaround, and the workarounds accumulate until the system's real behaviour is documented nowhere except in the scar tissue.

I have watched this happen in software, and I have watched the identical thing happen with machinery on a farm. Buy the implement first and you spend the season adapting the field to it. Establish what the field requires and the implement chooses itself. The one that chooses itself is usually smaller, older and cheaper than the one you would have bought.

how to find them

Three questions, asked about the thing you are actually building rather than about systems in general:

• What would make a user say this is broken even though nothing threw an error? That is usually an invariant, stated in the negative.
• What is the worst thing that can be true for one second? If the answer is nothing much, you have found a place where eventual consistency is genuinely fine, and those places are worth knowing too.
• What must survive the deletion of this codebase? Data, formats, URLs. Those are invariants about the world, not about the program, and they are the ones people forget to write down.

Write the answers as sentences, in a file, where the next person will find them. Tickets and tests come later. A test is an invariant made executable, which is only possible once the invariant has been written down.

the part that keeps

Tools change on a cycle of a few years and always will. The invariants of a gallery site have not changed since the first gallery: the withdrawn work stays withdrawn, the publish is all-or-nothing, the images outlive the code. They will read exactly the same in twenty years.

That asymmetry is the whole argument. Time spent on the layer that changes fastest is time you will spend again. Time spent on the layer that stays is the only kind that accumulates.

resultFind what must not change. Then make everything else cheap to change. In that order.

Everyone knows this window exists. Almost nobody measures it, because the fix is assumed to be expensive: blue-green environments, a load balancer, a health check, a rollout controller, a yaml file describing the rollout controller.

It isn't expensive. It's one system call.

the shape of the fix

Build the new site somewhere else entirely. Then move a single pointer.

$build = $buildsRoot.'/'.date('Ymd-His');
mkdir($build, 0755, true);

/* … write every page into $build … */

$tmp = "$root/.public.tmp";
@unlink($tmp);
symlink($build, $tmp);
rename($tmp, $publicLink);   /* before: old site. after: new site. */

rename() over an existing path is atomic on POSIX filesystems: rename(2) guarantees that a concurrent reader sees either the old entry or the new one, never a missing one and never a half-written one. The web server resolves public on every request. Before the rename it resolves to one finished build; after, to another finished build. There is no third state to be caught in.

The .public.tmp step matters more than it looks. symlink() fails if the target exists, so you cannot create the link directly over the live one — and unlink() followed by symlink() would open exactly the window we are trying to close, a window that is short but wide enough to serve a 404 to whoever is reading at that moment. Creating the link under a scratch name and renaming it into place keeps the whole operation to a single atomic step.

what this buys, precisely

problem

A deploy that is observable as a state — half old, half new.

invariants

A reader's request resolves to exactly one complete build. A failed build never becomes the live site.

decisions

Build to a fresh directory; publish by renaming a symlink; keep the last three builds on disk.

result

Deploys stop being events. There is nothing to schedule around and nothing to announce.

The second invariant comes free and is the one people notice later. If the build crashes halfway, it crashes in a directory nobody is serving. The live site does not know a deploy was attempted. You fix the error and run it again — no rollback procedure, because nothing rolled forward.

And rollback, when you do want it, is the same rename pointed at an older directory. Not a redeploy, not a revert commit, not a pipeline run: a rename. The last three builds are still sitting there.

the objection

The usual objection is that this only works for static output, and that real applications have databases and sessions and caches that cannot be swapped by renaming a directory.

That is true and it is also not an argument against doing it where it does work. A schema migration is genuinely hard; serving one consistent set of files is not. Most of what is deployed on any given day is the easy half wearing the difficulty of the hard half as an excuse.

the smaller lesson

The interesting part isn't the symlink. It's that the atomicity we wanted was already sitting in the filesystem, unused, while the industry built increasingly elaborate machinery to approximate it at a higher layer.

Before adding a system, it is worth asking which guarantee you actually need and how far down it already exists. Quite often the answer is: further down than you expected, and free.

resultThis site publishes in one rename(). The window is not small. It is absent.