Cache Storage and Maintenance

Cache Storage and Maintenance

On-disk cache files support optional compression, deferred writes, and file protection.

Write timing

performance.cache_write_strategy controls when buffered cache writes flush:

Value	When writes hit disk
immediate	After each cache entry
phase	End of each phase+scope invocation (common default)
end	End of the entire Beez run

If Beez crashes mid-run with phase or end, some cache entries may not be persisted yet. The next run recomputes missing entries.

Compression

Configured under cache.compress:

cache = {
    compress = {
        algorithm = "gzip",  -- none, gzip, zlib, rle, deflate, delta, vbyte
        level = 6,
        mode = "auto",       -- never, always, auto
    },
},

Cache files are stored in an envelope format with a header and optional compressed body. Metadata is tracked in .cache/beez-compress.meta.

Recompress after config change

beez --update

Rewrites cache files to match current compression settings. Prints how many files were migrated. Does not invalidate cache keys.

File protection

cache.protect = true applies platform-specific protection on cache files after write (read-only or similar) to reduce torn reads during concurrent access.

Cleaning cache

Delete everything

beez --clean-cache

Or manually:

rm -rf .cache

Selective cleanup

Delete	Effect
.cache/entries/	Step manifests; indexes may repopulate
.cache/index/	Fast lookup; full key lookup still works
.cache/success/	All per-file success state
.cache/logs/	Logs only; does not affect build cache

Logs vs cache

.cache/logs/ holds run and worker logs. It is not part of the cache invalidation system. Add .cache/ to .gitignore.

CI recommendations

Pattern	Reason
Cache .cache/ between CI jobs	Reuse step and success cache
Key cache on lockfile + toolchain	Separate caches per compiler
beez --clean-cache on cache schema breaks	After major Beez upgrades
beez --no-cache for release builds	Optional policy for reproducibility

Configuration reference

See Cache Settings for all cache.* keys.

CLI reference

See Cache and Maintenance Flags.

Next steps

• Caching Troubleshooting
• Cache Keys and Invalidation