feat: compile-cache executor + fastcache-cc sccache-style launcher

[Yaraslaut]

Compile-cache executor + fastcache-cc launcher

Implements the server-side executor from docs/specs/executor.md §5 and a
drop-in sccache-style compiler launcher that uses it — together making a
shared compile cache correct across machines at different checkout depths,
ending the /showIncludes poisoning treadmill.

The problem

A cached compile value is not a portable blob. On a hit, the producing
machine's captured /showIncludes output is replayed verbatim; Ninja records
those header paths into .ninja_deps. When the producer's build-tree→header
depth differs from the consumer's (canonically, a CI runner nested one level
deeper), the replayed paths don't exist on the consumer, so Ninja marks
everything dirty and no-op builds recompile hundreds of objects. The existing
client-side repair is a last-writer-wins treadmill.

The approach (Option C — server canonicalizes, client localizes)

A new IProtocolHandler (CompileCacheHandler, autodetect magic 0xFC) over
the unchanged IStorage stack:

• On STORE: canonicalizes every path in the value's captured text regions
  into machine-neutral <SRCROOT>/<BUILDTREE> tokens, using the producer's
  layout carried in the frame. The object blob is a separate field and is never
  rewritten. The stored value has no machine identity — so no producer can
  poison a shared entry.
• On FETCH: serves the canonical value verbatim; the client localizes tokens
  to its own layout. The server stays off the per-consumer transform path.

The canonicalization rule is normative in docs/specs/compile-cache-canon-v1.md
with conformance vectors as the client↔server parity contract.

Server components

Area	Component
Path rewriting	CompileCache/PathCanon — absolute↔token + showIncludes/MSVC-diagnostics/depfile region grammar
Value framing	CompileCache/CompileValue — object blob (untouched) + grammar-tagged text regions
Cohort tracking	CompileCache/CohortManifest — cohort-id→key-set + reverse index
Storage hook	IStorage::Prefetch — warm a tier with no read side effect (LayeredStorage pulls L2→L1; forwarded through all decorators)
Protocol	ProtocolAutodetect 0xFC flavor + CompileCacheHandler (STORE/FETCH + leading-key cohort prefetch)

The launcher — tools/fastcache-cc

A real drop-in for sccache, wired via CMAKE_CXX_COMPILER_LAUNCHER:

• Keys on hash(compiler-id + preprocess output + checkout-relativized args) — same content at different checkout roots ⇒ same key, so machines share entries. Isolated in CacheKey for tuning.
• HIT: reproduces the object and replays stdout/stderr with /showIncludes localized to the local layout, so Ninja records valid deps.
• MISS: runs the real compiler (stdout/stderr captured separately via CreateProcess), STOREs the canonicalized result, passes output through.
• Any cache error → falls back to a plain real compile and (with FASTCACHE_VERBOSE) warns. The build never breaks because the cache is down.
• Config via FASTCACHE_ADDR/SRCROOT/BUILDTREE/COHORT/VERBOSE env (the SCCACHE_* model).

Testing

• Full suite green (881/881, clangcl-debug, PEDANTIC_COMPILER_WERROR=ON), including unit tests for every server component, the launcher's command parsing and cache-key parity across checkout roots, and a poisoning-regression test.
• Real-compilation E2E (cl.exe + clang-cl):
  • compile-cache-testclient/run-crossdepth.ps1 — store from a deep path, fetch+localize from a shallow one; every include path resolves. ALL CROSS-DEPTH CHECKS PASSED.
  • fastcache-cc/run-launcher-e2e.ps1 — drives the launcher as the compiler: first compile MISSes and stores; second (object deleted) HITs and reproduces the object byte-identically; content stored from a deep checkout HITs from a shallow one with /showIncludes localized. ALL LAUNCHER E2E CHECKS PASSED.

Whole-codebase validation (real compile database)

The launcher was exercised against a large real C++ codebase by replaying its
compile_commands.json (4223 TUs) through fastcache-cc twice (populate, then
measure). Second-pass hit rate: 99.7% (393/394 cacheable) on a 400-TU
sample. This surfaced and fixed several real launcher defects (all now
covered by the fix commit):

• Keying preprocess must be captured from stdout only — merging 2>&1
  folded diagnostics in at a non-stable interleave point, making the key
  nondeterministic (nothing ever hit).
• Child stdout/stderr must be drained concurrently — sequential draining
  truncated large (>64 KB) preprocessed output nondeterministically.
• Windows arg quoting hardened (backslash runs before a closing quote) so
  MSVC/SDK include paths with spaces (C:\Program Files (x86)\…) survive.
• TUs referencing __TIME__/__DATE__/__TIMESTAMP__ are skipped (they
  re-key every second; same as sccache).

Operational note: objects can be large (observed max ~122 MB), so run the
daemon with --storage-max-value 256M (this also raises the frame-payload cap);
the 16 MiB default would leave ~7% of this codebase's objects uncached.

Scope / follow-ups

• The cache key is a deliberate v1 (preprocess + relativized-args hash), isolated so it can be tuned against real dev↔CI hit rates.
• Localized path separators are normalized to / in some segments (Ninja matches separator-insensitively — cosmetic); non-showIncludes diagnostic paths aren't localized yet.
• Phase-2 grammar should still be reconciled against the empirical /showIncludes diff in executor.md §6 before freezing.

Design record

• docs/superpowers/specs/2026-07-23-compile-cache-executor-design.md
• docs/superpowers/plans/2026-07-23-compile-cache-executor.md, …-fastcache-cc-launcher.md
• docs/specs/compile-cache-canon-v1.md

🤖 Generated with Claude Code