Module cache 

Persistent on-disk cache for Phase K.

The cache stores a serialized FileIndex per PHP file, keyed on (uri, content). On a warm start scan_workspace reads the cached index instead of parsing the file, shrinking cold-start I/O from O(parse) to O(read + bincode-decode) — roughly 10–50× faster per file.

Layout

~/.cache/php-lsp/<schema-version>/<workspace-hash>/<entry-hash>.bin

• <schema-version> — php-lsp crate version; bumping it rotates the entire cache so old entries are never decoded against a newer schema.
• <workspace-hash> — blake3 of the canonicalized absolute path of the first workspace root, truncated to 16 hex chars. Two separate projects get isolated caches; two checkouts of the same project at the same absolute path share one.
• <entry-hash> — blake3 of the bytes uri || 0x00 || content, truncated to 32 hex chars. Editing a file changes the content → new key → cache miss; a different file at the same URI also gets a different key.

Format

bincode v2 (binary, fast, schema-stable via serde derives on FileIndex et al). Files are written atomically via a temp-file rename to avoid half-written entries on an interrupted shutdown.

Invalidation

Rotating the schema version invalidates everything; rotating the content invalidates one file. There’s no LRU or cleanup yet — Step 2 will add a size cap + orphan sweep.

Structs

CacheKey

Identifies a single cache entry. Opaque — callers produce it via WorkspaceCache::key_for and pass it straight back to read/write.

WorkspaceCache

Handle to the cache directory for a single workspace. Construction is cheap (creates directories on demand); the same handle can be shared across threads via Arc — it holds no mutable state.

Constants

CACHE_SIZE_CAP

Size cap (bytes) for a single workspace’s cache directory. At startup, if the directory exceeds this, we reset it — simpler than LRU eviction and the rebuild cost is bounded (it’s just the next workspace scan running as if cold). 512 MiB fits a mega-workspace (50 k files × ~10 KB average FileIndex) with headroom and is small enough that no reasonable disk will choke on it.

FILE_INDEX_SCHEMA

Bump this constant (and the matching literal in [schema_version]) when FileIndex or any type it contains gains, loses, or renames a field. Rotating it causes every cached entry to be treated as a miss on the next cold start, regardless of whether the crate version changed.