Module root_cache 

These files coordinate safe access to a project-root cache: a writer lease ensures only one process updates the cache at a time, and read-marker files let cleanup see which readers are still using the cache.

Writer leases are stored at <storage>/callgraph/<artifact_cache_key>/writer.lease and <storage>/inspect/<project_scope_key>/writer.lease. They use the fs_lock JSON format with a writer_epoch nonce so a writer can detect if another process has taken over before publishing changes or starting SQLite write transactions.

Read markers track active SQLite readers so cache cleanup can tell when it is safe to remove old data. They are stored under <cache-domain>/readers/<generation-label>/<pid>.<hostname>.<created_at_ms>.<seq>.json; the JSON records the process identity and creation time, mtime is used as a heartbeat for cleanup across hosts, and the PID is used for cleanup on the same host. Marker files are created 0600 so they do not expose checkout activity or let another local user delete a protected marker.

Structs

ArtifactAccess

Root-scoped capability that distinguishes shared repository artifacts from mutable state private to one checkout.

ArtifactPublishEpoch

Serializes artifact supersession with the final disk publication step. Advancing an epoch either happens before a stale worker checks and prevents its publish, or after that worker has fully published the still-current generation. This closes the check-then-publish race of a bare atomic epoch.

ReadMarker

ReadMarkerMetadata

ReadMarkerSweep

WriterLease

Enums

RootCacheDomain

Constants

READ_MARKER_CROSS_HOST_STALE_MS

Cross-host markers cannot use local PID liveness, so they expire after the same conservative 5x stale-heartbeat window used by filesystem locks.

READ_MARKER_TOUCH_INTERVAL_MS

Read-marker heartbeats refresh no more often than the filesystem lock heartbeat. Active readers piggyback this on normal read paths instead of spawning a thread per connection.

Functions

configure_artifact_access

Register the worktree topology already detected by configure so artifact APIs can enforce it without repeating a Git subprocess on every write path.

protected_read_marker_exists

read_marker_dir

storage_allows_root_keyed

sweep_read_markers

writer_lease_path