Skip to main content
strata check keeps a persistent result cache, on by default, so warm runs skip re-evaluating files whose inputs have not changed. On a large repository this turns a multi-second check into a fast one without changing a single output byte. The cache lives in a SQLite database at .strata/cache/v1.db in the repository root. Add .strata/ to your .gitignore.

​
The contract

The cache is a pure optimization with one contract: a cached run produces byte-identical output to an uncached run. Two properties enforce it. Reuse requires proof. A file’s cached result is reused only when everything that produced it is provably unchanged:
  • the file’s own content hash,
  • the answer to every cross-file question evaluation asked while checking it (does this path exist, what does this directory contain, what is in this imported file), re-asked and compared on every run,
  • the configuration, the selected ruleset, and the Strata implementation itself, all content-hashed into one cache identity.
There is no dependency graph to maintain and no timestamp heuristics. Each result records the questions its rules actually asked; reuse replays those questions against the current filesystem. A file that newly appears or disappears changes an answer, so it invalidates exactly the results that depended on it. Editing config, a rule, or upgrading Strata changes the cache identity, so the whole cache is rebuilt. Failure degrades, never corrupts. An unreadable, corrupt, or foreign cache entry is a cache miss: the file is recomputed fresh. A broken cache database degrades the run to fully uncached with a warning on stderr telling you to delete .strata/cache if it persists. No cache failure mode can change an exit code or a diagnostic.

​
Configuration and flags

The [cache] table has two keys: enabled (default true) and require_cacheable (default false). On strata check, --cache and --no-cache override the config for one run, and --cache-stats prints hit/miss/invalidation/write counts to stderr, or Cache: disabled (<reason>) when caching was unavailable. See strata check for the flag reference.

​
Custom rules

A custom rule body is arbitrary Python, so it cannot be assumed to only read tracked inputs. By default, selecting any custom rule disables caching for the whole run. Setting require_cacheable = true verifies every selected custom rule at startup and keeps such runs cached; see Custom rules for the hermetic contract that verification enforces.

​
When something looks wrong

strata check --no-cache runs with the cache fully bypassed. If cached and uncached output ever differ, that is a Strata bug; please report it. Deleting .strata/cache/ is always safe - the next run rebuilds it.