Module cache 

The snapshot cache: the two or three answers a fast resolution cannot afford to compute, kept beside the shared server’s lease under the checkout-local half of the layer.

Why there is a cache at all

Counting what the layer holds means building the index, which reads and validates every declared file. That is the right cost for a command a person waits on and an impossible one for a shell prompt. So a full resolution writes what it learnt, and a fast one reads it back.

Why it is three caches and not one

Each tier carries its own fingerprint over its own inputs, so editing the justfile expires the workflows and leaves the counts alone, and committing a rule expires the counts and leaves the workflows alone. One fingerprint over everything would make every change invalidate everything, which is the cheap version of this design and the one that makes a warm cache rare.

What is in it, and what may never be

Counts, recipe names and their doc comments, toolchain version strings, and a digest of the last snapshot. Nothing read from the environment, no file contents, no paths outside the repository, and nothing a credential could be hiding in — asserted by the_cache_holds_nothing_that_could_be_a_secret.

A cache that cannot be read is a cache miss, never an error: a truncated write, a file from another version, a directory that is read-only. Writes are atomic — a temporary file and a rename — so a reader sees either the previous entry or the whole new one.

Structs

Cache

The cache file of one checkout.

CachedTier

What a fast resolution takes from an earlier full one.

Entry

One cached answer with the fingerprint of the inputs it was computed from.

Constants

CACHE_PATH

Where the cache lives, relative to the checkout-local half of the layer (.ai/local/). Beside the shared server’s lease, for the same reason: it belongs to this checkout, it is never tracked, and a fresh clone starts without it by design.

SCHEMA

The cache document’s own schema. A document of any other schema is a miss.

TOOLCHAIN_LIFETIME

How long an installed toolchain version is believed. Nothing in the repository changes when a person upgrades their compiler, so no fingerprint over the repository can notice it; a bounded life is what makes that self-heal instead of lying until the next full resolution.

Functions

fingerprint_of

A fingerprint over a set of files: their paths, sizes and modification times.

now_seconds

Seconds since the Unix epoch, or 0 on a machine whose clock is before it.