Cache Keys and Invalidation

Cache Keys and Invalidation

Understanding what invalidates cache entries helps avoid surprise full rebuilds or stale skips.

Step cache invalidation

A step cache hit fails (step runs again) when any of these change:

Trigger	What changed
Input files	Content (key) or size/mtime (index) of files matched by input/mutate
Outputs missing	Declared output path deleted or not found
Shell command	run string text
build.lua	Content hash (for Lua callback steps)
Step config	config table / configure_step() / task overlay
Environment	Any variable in env.hash_vars (unless in ignore_vars_for_hashing)
Beez upgrade	Version string in key and index
--no-cache	Cache disabled for run
--dry-run	Lookups skipped (steps not executed anyway)

What does not invalidate step cache

• Changing an unrelated file outside input/mutate globs
• Vars not listed in env.hash_vars
• Renaming the step's phase or scope (treated as a different step with a separate index file)

Success cache invalidation

A file_success_cached hit fails when:

Trigger	Effect
File content changes	file_hash mismatch
Included headers change	inputs_hash mismatch (via #include "..." scan)
File deleted	Not a regular file anymore
Step config changes	config_hash mismatch
Revision bump	e.g. lint_rev = "3"
Beez upgrade	version mismatch
Previous failure	Path listed in misses file (re-checked via get_cache_misses)

Generic success_cached(key) invalidates when config, version, or key identity changes (no file hash).

Revision keys (recommended practice)

Add explicit revision fields to step config when tooling changes without source changes:

configure_step("lint", {
    patterns = { "src/**/*.cpp" },
    lint_rev = "1",
})

configure_step("format", {
    patterns = { "src/**/*.cpp" },
    format_rev = "1",
})

Bump the revision when:

• .clang-tidy or formatter config changes
• Lint rule sets change
• Docker image or tool version changes (if not captured in env vars)

Environment fingerprint

Vars in env.hash_vars are sorted and concatenated into a fingerprint string for step cache keys.

Default hashed vars: CC, CXX, CFLAGS, CXXFLAGS, LDFLAGS, BUILD_TYPE.

Add custom vars when they affect build output:

env = {
    hash_vars = {
        "CC", "CXX", "BUILD_TYPE", "MY_TOOLCHAIN",
    },
},

Exclude noisy session vars via ignore_vars_for_hashing.

Beez version upgrades

Both caches embed the Beez version. Upgrading Beez invalidates existing entries. This is intentional when cache format or logic changes.

Manual invalidation

Action	Effect
beez --clean-cache	Deletes entire cache root
Delete .cache/success/ only	Clears success cache, keeps step cache
Delete .cache/index/	Forces step cache to recompute via content keys
rm .cache/index/my-step__*__*.index	Invalidate one step's fast index

Stale hit prevention

Step cache requires outputs to exist on disk. If someone deletes build/app but cache index remains, Beez runs the step again even when inputs are unchanged.

Success cache re-hashes file content on every file_success_cached check.

Next steps

• Cache Storage and Maintenance - --update, compression
• Caching Troubleshooting
• Environment Variables