Build Cache and Store

Sigil keeps content-addressed build inputs and outputs in a store. Reusing a verified object avoids recompiling it; changing an input or toolchain creates a different object instead of overwriting the old one.

Default location

The default store is:

1. $SIGIL_STORE, when set
2. $XDG_CACHE_HOME/sigil/store
3. $HOME/.cache/sigil/store

SIGIL_STORE is an explicit override. Sigil expects that location to be writable and reports an error immediately when it is not.

Read-only stores in sandboxes

Some sandboxes, including managed Codex workers, expose the normal user cache as readable but not writable. Sigil detects this by attempting a small write; it does not rely on Unix permission bits, which may not reflect sandbox policy.

When the default store is read-only, sigil build automatically uses two layers:

• the existing default store as a read-only fallback
• a writable store under /tmp as the upper layer

Reads search the upper layer first and then the fallback. New content, build records, locks, and garbage-collection roots are written only to the upper layer. No Codex configuration or environment variable is required, and the build prints both paths when it activates this mode.

The upper path is stable for a given default-store path, so workers that share the same /tmp can also share the overlay. It is named like:

/tmp/sigil-store-overlay-v1-<store-path-hash>

/tmp is normally ephemeral. Losing the overlay is safe: Sigil will recreate it and can still reuse verified objects from the fallback. It may, however, need to rebuild objects that existed only in the overlay.

Integrity and concurrency

Every object is verified against its content hash before Sigil publishes it from either layer. A corrupt object in a read-only fallback is treated as a cache miss and is not modified. Sigil can then rebuild the object into the writable layer.

Writers coordinate through per-content locks in the writable store. A verified cache hit does not acquire a lock, which also permits reuse from an immutable store. Permission failures are reported as errors rather than being mistaken for lock contention.

Choosing another store

Set SIGIL_STORE when you deliberately want one writable store:

SIGIL_STORE=/work/cache/sigil-store sigil build

Because this is an explicit choice, Sigil does not silently add a /tmp overlay if the selected path is unwritable. This makes configuration mistakes visible and keeps CI behavior predictable.