zccache Architecture

This document is the index for zccache's architecture specification. Each subsystem is documented in a separate file under docs/architecture/.

Documents

Document	Lines	What it covers
architecture/overview.md	~280	System diagram, all 9 component descriptions and key interfaces
architecture/data-flow.md	~160	Cache hit, cache miss, passthrough traces + rustc key-scope rules (env-deps, incremental, crate types)
architecture/ipc.md	~100	Transport abstraction, socket discovery, connection lifecycle, compile progress heartbeats, errors
architecture/metadata-cache.md	~130	In-memory cache data model, confidence levels, watcher integration
architecture/artifact-store.md	~130	Disk layout, bincode index schema, LRU eviction, corruption detection
architecture/rust-artifact-plan.md	~120	Rust plan ownership, thin/full semantics, restore hardening, backends, diagnostics, CLI contract
architecture/embedded-service.md	~290	Embedded service MVP boundary, audit continuity, soldr/fbuild integration design
architecture/target-cache.md	~70	Legacy action target snapshot ownership, outputs, and rust-plan boundary
architecture/runtime.md	~130	Concurrency model, correctness guarantees, failure modes, crash recovery
architecture/portability.md	~200	Platform differences, host-platform boundary (zccache-platform), path handling, file identity, future extensions

Cache-root lifecycle logs are verified by the shared zccache-audit catalog at perf and integration boundaries. This keeps CI policy in Rust and makes a failed cache-root audit retain its diagnostic JSONL evidence.

Quick Reference

• High-level design → overview.md
• "How does a cache hit work?" → data-flow.md
• Nested Dylint driver caching → data-flow.md
• CLI↔daemon communication → ipc.md
• Compile queue visibility, progress-based wedge detection → ipc.md § Compile progress heartbeats
• File change detection → metadata-cache.md
• Disk cache & eviction → artifact-store.md
• Private compiler staging root → portability.md
• Daemon-owned bounded disk retention → artifact-store.md
• Transactional directory outputs → artifact-store.md
• Reflink / hardlink COW safety → artifact-store.md
• soldr target artifact contract → rust-artifact-plan.md
• Embedded soldr/fbuild service integration → embedded-service.md
• Embedded maintenance limits and shutdown reporting → embedded-service.md § Maintenance limits and task ownership
• Shared periodic maintenance schedule (both service modes) → embedded-service.md § Maintenance limits and task ownership
• Legacy action target snapshots → target-cache.md
• Thread safety & crash safety → runtime.md
• Async/process bridge — watchdogs, cancellation & timeouts (deadlock hardening) → runtime.md § Async / process bridge
• Where zccache writes on disk (ZCCACHE_CACHE_DIR contract) → runtime.md § Cache root invariants
• Host no-spawn guard (ZCCACHE_NO_SPAWN, embedding hosts) → runtime.md § Host no-spawn guard
• Uncached-fallback policy (ZCCACHE_FALLBACK, CI hard-error) → runtime.md § Wrapper fallback policy
• Standalone daemon identity, deployment & lifecycle (argv[0] single binary, version-rooted deploy, versioned endpoints) → runtime.md § Standalone daemon identity, deployment & lifecycle
• Rejected depgraph snapshots — quarantine, recovery, why no migration → runtime.md § Depgraph snapshot quarantine
• Windows/macOS/Linux differences → portability.md
• Host-platform boundary (zccache-platform) → portability.md
• Compile journal fields & miss_reason enum → journal-schema.md

See also: DESIGN_DECISIONS.md for rationale behind key choices, ROADMAP.md for implementation phases. For embedded mode, start with architecture/embedded-service.md, especially the MVP status table: Soldr integration is landed; fbuild remains open.