Step Cache

Step Cache

The step cache skips a whole step when Beez determines the step already produced its outputs and nothing material has changed.

When a step is cacheable

A step is cacheable if it has at least one artifact pattern:

step({
    name = "compile",
    phase = "build",
    scope = "default",
    input = { "src/**/*.cpp" },
    output = { "build/app" },
    run = "cmake --build build",
})

No input, output, or mutate means the step always runs.

Skip decision

On each step run, Beez checks (in order):

1. Per-step index (.cache/index/<name>__<phase>__<scope>.index) if present:

   • Command fingerprint matches (shell command or Lua callback + build.lua hash)
   • Step config fingerprint matches
   • Beez version matches
   • Input file stamps match (path, size, modification time)
   • All recorded outputs still exist on disk

2. If the index misses, content-addressed key lookup in .cache/entries/<key>.manifest:

   • Key derived from input file content hashes, step identity, config, env, version
   • Skip if manifest exists and outputs still exist

If all checks pass, the step is reported as a cache hit and not executed.

Cache key ingredients

The content-addressed key combines:

Component	Source
Step identity	name, phase, scope
Command	Shell run string, or <callback> + hash of build.lua
Input files	Content hash of each file matched by input + mutate globs
Step config	Serialized config / configure_step() table
Environment	Fingerprint of env.hash_vars (see Environment Variables)
Beez version	Installed Beez version string

Input patterns are the union of input and mutate globs.

What gets stored

After a successful step run:

• Manifest at .cache/entries/<key>.manifest listing step name and output paths
• Index at .cache/index/<sanitized-name>__<phase>__<scope>.index with:
  • Cache key, command, config, version
  • Input stamps (path, size, mtime)
  • Output paths
  • Last run duration (for time-saved display)

Output tracking

After execution, Beez records which files the step produced:

Step declares	Outputs recorded as
output globs	Expanded glob matches
mutate only (no output)	Expanded mutate matches
Neither output nor mutate	Directory snapshot diff under build/ (or dirs from output patterns)

See Artifact Patterns.

Shell vs Lua steps

run type	Command fingerprint
Shell string	Exact command text
Lua function	Hash of build.lua (callback body is not hashed separately)

Changing build.lua invalidates Lua callback step cache entries.

Worker subprocess cache

Workers spawned via ctx:spawn() with inputs or outputs can use the same step cache machinery internally (treated as a synthetic step). See Step Context.

Configuration

Setting	Effect
cache.enabled	Master switch
cache.path	Root directory
cache.hash.*	Hash algorithm for keys and file content
performance.cache_write_strategy	When index/manifest writes flush to disk
env.hash_vars	Env vars in key fingerprint

See Cache Settings.

CLI

beez build --no-cache     # always run cacheable steps
beez --clean-cache build  # wipe cache first

Next steps

• Artifact Patterns - input, output, mutate
• Cache Keys and Invalidation - bump revisions, version upgrades
• Success Cache - finer-grained per-file caching