uv: Orientation

uv turns a declarative Python environment into a consistent filesystem state. Its architectural center is a staged pipeline: discover and resolve packages, reuse or prepare artifacts, calculate an install plan, lock the target, and apply that plan using cache-backed files.

requirements → resolver ↔ concurrent metadata fetch
                         ↓ Resolution
installed state → Plan → prepare wheels → environment lock → uninstall/install
                                  ↕
                       append-oriented shared cache

The cache and target environment have different concurrency contracts. Cache entries are designed for concurrent readers and writers; mutation of one environment is guarded by a cross-process file lock.

Design thesis

uv overlaps slow preparation aggressively while assigning a separate limit and ownership protocol to each scarce resource, then exposes artifacts only after validation and atomic publication.

• Download, build, and install budgets are distinct semaphores.
• Same-key in-flight work is shared before a cache entry exists.
• Immutable cache artifacts support broad concurrency.
• One target lock protects the multi-file environment transition.

We will preserve staged resolution, per-resource concurrency limits, in-flight request deduplication, bounded blocking work, immutable artifacts, atomic cache publication, target locking, and structured failure context.