Module cache 

Persistent on-disk cache for Phase K.

Status: infrastructure layer only. This module exposes the primitives — directory layout, content hashing, serde round-trip — that a later commit will wire into scan_workspace to skip re-parsing on warm start. Nothing in backend.rs / document_store.rs consumes it yet.

Layout

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

• <schema-version> — php-lsp crate version concatenated with the mir-codebase version (the latter owns StubSlice’s schema, so bumping either rotates the cache).
• <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 StubSlice 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 StubSlice) with headroom and is small enough that no reasonable disk will choke on it.