Architecture overview

This section is a tour of how zut works inside, for contributors and the curious. The authoritative, detailed design contract is docs/ARCHITECTURE.md in the repository — this is the friendly companion.

Design goals

• Correctness by construction — output is a pure function of declared inputs; undeclared inputs are physically unavailable (the sandbox).
• Fine-grained incrementality — the cache unit is the action.
• Speed — parallel by default, content-addressed caching, early cutoff.
• Rust & Zig as peers — linked through the C ABI, neither a bolt-on.
• Remote-ready — the execution path is shaped like the Bazel Remote Execution API (REAPI), so remote caching/execution slot in cleanly.
• Extensible — rules are Starlark definitions over primitives.

The shape of a build

BUILD / .bzl  ──►  unconfigured graph  ──►  configured graph  ──►  actions  ──►  outputs
   (Starlark)        (what targets exist)     (select() resolved)   (cacheable)

Loading, configuration, and analysis are memoized as keys in the incremental engine (DICE); execution is keyed separately by the content-addressed action cache. The next two chapters unpack these:

• The five layers — from BUILD text to materialized outputs.
• Content addressing & the CAS — the hashing substrate everything stands on.

And the code map:

• Repo & source layout — which directory does what, and which way the dependencies point.