Bases and the cache

A base is what hiiu build produces: an immutable copy of one revision of your app, with the interception overlay written over it and its dependencies installed. Everything downstream reads a base rather than your repository.

Addressed by what went into it #

A base is named by a content address computed from the three things that determine its contents: the source revision, the configuration it was built against, and the generator version that wrote the overlay.

That is why the cache is trustworthy. A hit is not a guess that nothing changed, it is a proof that the three inputs are the same three inputs, so the output would be identical. A second build of an unchanged revision re-runs nothing and finishes immediately.

It is also why a dirty working tree is exit 3. An uncommitted change has no revision, so it has no address, so there is nothing to cache it under and no way to say later what a base was made from.

Where it lives #

~/.cache/hiiu/bases/<id>/

Nothing lands in your repository. Ever. Two roots hold everything hiiu keeps:

Path	What
~/.config/hiiu/config.json	Preferences
~/.cache/hiiu/bases/<id>/	The content-addressed base cache
~/.cache/hiiu/bundles/<id>.tgz	Built bundles, which hiiu serve runs
.hiiu/	Per-workspace overlay, in a forked workspace, never upstream

Both roots are overridden by HIIU_HOME, which exists so tests never touch a real home directory. A relative HIIU_HOME is a usage error naming the variable, rather than a silent fallback that would put ./cache in whatever directory you happened to be standing in.

Installed with the app's own tools #

The base installs with the app's own package manager, from the app's own lockfile. Not a normalised one, not a faster one.

That is not politeness, it is fidelity: hoisting differs between package managers, and a base installed with the wrong one is a copy of an app that subtly is not yours. The whole value of prototyping on the real app is that it is the real app.

It also means the build reaches the network, which is why "hermetic" is a claim about the running copy rather than the build. What hermetic means is the page on that distinction.

What it carries about itself #

A base writes a manifest at <app>/.hiiu/base.json describing what it is. That is what makes a cache hit checkable rather than assumed, and it is what a later promotion step subtracts and restores when turning a prototype's diff back into a patch against the real repository.

Who reads a base #

• hiiu dev runs the app's own dev server inside one.
• hiiu fork copies one into a workspace for a designer.

Both resolve the base exactly as build does, so both get the cache hit, and neither can drift from what build would have made.