# Incremental builds and cache

SpriteForge uses two immutable content-addressed cache layers under `.sfcache/`:

- `raw/<input_hash>.npz` stores expensive backend RGBA output;
- `artifacts/<artifact_hash>.sfa` stores palette-dependent postprocessed output.

The input hash covers the normalized asset specification, every dependency file
reported by the backend, the backend version, and the raw-cache format version.
The artifact hash additionally covers the shared palette and postprocess
version. Cache writes use a temporary file followed by an atomic replace.

This split is intentional: changing a palette may require cheap requantization,
but must never rerun a future multi-hour Blender render.

```text
sf build assets.yaml --jobs 8
sf build assets.yaml --asset changed_actor --jobs 8
sf build assets.yaml --rebuild-palette
```

`--jobs N` runs independent backend tasks in a process pool on Windows and
Linux. The CLI reports counts for newly generated raw assets, raw-cache hits,
and final artifact-cache hits.

An existing `palettes.sfp` is stable across ordinary incremental builds. Use
`--rebuild-palette` only with an unfiltered full build; SpriteForge rejects a
filtered palette rebuild because it would invalidate unchanged indexed assets.

The cache is disposable and never a source of truth. Manifests and source files
remain authoritative.