Glossary

Seventeen terms, defined as Flintstack uses them, each linked to where it matters.

The vocabulary used across these pages, in one place. The terms are not generic - each means something specific to how Flintstack is built, and the definitions link to the page where the term does its work. If a word here is unfamiliar, the design notes are the long version.

Cache key: The 128-bit name of an entry, the first half of a SHA-256 over the toolchain identity, the normalized argument vector, the input digests and the allowlisted environment. Two builds with the same key are treated as the same build. See flint key.
Content-addressed store: A store where an object's location is derived from its contents, not from a name chosen by hand. It makes duplicate results free and makes a wrong lookup impossible to confuse with a right one.
Entry: One stored compiler result: the output file or files, a header, and since 0.7.0 a trailing digest over both that is checked on every read.
Shard: One of the directories the store is split across. Since the 0.7.0 format change the shards are the only source of truth; there is no separate index to disagree with them.
Hit / miss: A hit is a lookup that finds a usable entry and skips the compiler entirely. A miss runs the compiler and stores the result under the key computed before the run, so a miss costs one extra stat of each input, not a second compile.
Eviction: Removing entries to stay under max_size. Sweeping starts at 95 % of the ceiling and stops at 85 % so it does not run continuously - the hysteresis added in 0.4.0.
LRU: Least-recently-used, the default eviction policy: the oldest-touched entries go first. The alternative, size, evicts the largest first and suits a store dominated by a few huge objects.
TTL: A maximum age after which an entry expires regardless of use. It uses wall-clock time, so a clock skew between client and daemon distorts it; "0" disables it.
Backend: A tier of storage. fs is a local directory and is always the first tier; objs is object storage over signed HTTP; peer is another daemon over TCP. Backends are tried nearest first.
Toolchain probe: How the key captures the compiler. version trusts the version string; digest hashes the binary and survives a distribution patching the compiler without bumping the version - the setting added in 0.8.0.
Normalization: Stripping the working directory out of the argument vector so two checkouts in different directories share entries. On by default; turning it off is the most common reason a cache never matches.
Environment allowlist: The short list of environment variables folded into the key. Hashing the whole environment, as the very first versions did, made every entry unique under CI, which is why the allowlist exists.
Hermeticity: The assumption that a build reads only the inputs it declares. Flintstack does not enforce it - if a build reads an undeclared file it will cache the wrong answer, the sharpest edge in the design.
Wrapper: The flint wrap command that sits in front of the compiler. It is deliberately boring about failure: unreachable daemon, uncomputable key or a vanished input all fall through to the real command with its real exit status.
fsync mode: How durably finished objects are flushed: none, entry (flush each object, the default), or strict (also flush the directory, about 8 % slower).
Write queue: The bound on pending stores. When it is full the write is dropped and logged, never blocking the build, because the compiler has already produced the real output by then.
Label: A free-form string attached to stored entries with wrap --label so that flint stats --by-label can attribute hits to parts of a build. It is not part of the key.

Last updated: 2026-09-20