build: centralize fast-path cache artifacts in a shared orchestrator contract

[zackees]

Problem

PR #156 added Teensy warm-build fast-path support, but the cache contract is still assembled ad hoc inside each orchestrator.

Today each platform can independently decide:

• which artifacts count as required for a cache hit
• where the persisted fingerprint lives
• how watch sets are collected
• when fingerprint save / reuse / zccache mark-success happens

That duplication is already visible across AVR, ESP32, and now Teensy. It creates a drift risk where one orchestrator participates in the warm-build cache differently than another, or a future builder writes artifacts outside the shared cache path without being reflected in the fast-path contract.

Requirement

All artifacts relevant to warm-build caching should be part of a shared base orchestrator / pipeline contract so every orchestrator and builder goes through the same cache system instead of open-coding its own artifact list and persistence logic.

The architectural rule should be:

• orchestrators declare their cacheable outputs through one shared interface
• the shared layer owns fingerprint path conventions, required-artifact checks, and fingerprint persistence
• builders / compile-db generation / firmware emitters do not create cache-relevant side outputs outside that same contract

Why this matters

Without a central contract:

• warm-build correctness depends on each orchestrator remembering to include every relevant artifact
• compile database, firmware, and sidecar outputs can silently drift by platform
• new platforms are encouraged to copy/paste an existing orchestrator instead of extending one cache system
• future fixes to cache behavior have to be repeated per orchestrator

Scope

A follow-up refactor should:

1. Extract the common fast-path artifact/fingerprint lifecycle out of per-platform orchestrators.
2. Define a shared way for platforms to declare required artifacts and watched roots.
3. Ensure compile database outputs and any other cache-relevant side artifacts are declared through that shared mechanism.
4. Leave platform-specific metadata hashing only for genuinely platform-specific inputs.

Non-goals

• Not redesigning the fingerprint hash format again unless the shared contract requires it.
• Not changing warm-build semantics for already-correct platforms beyond moving them onto the shared path.

Related

• perf: extend watch-set fingerprint cache to AVR / Teensy / other orchestrators #121
• [META] fbuild build cache must survive CI tar-extract / cross-runner restore #147
• Add shared warm-build fast path to Teensy orchestrator #156
• build: make hash_files stable across workspace roots #155