Atlas Index and Concept Ledger
The ledger keeps breadth honest: new libraries must add a primary design lesson, not merely another example of a familiar pattern.
Current specimens
| Library | Primary lesson | Important secondary lessons | Closest overlap | Deep-dive value |
|---|---|---|---|---|
| Clap | typed schema for external commands | derive, generated help, validation | Serde macros | high |
| Serde | consumer-owned data model | traits, derive, format separation | Clap macros | very high |
| Rayon | extension trait changes execution | ordering, Send/Sync, work splitting | Iterator, Itertools | high |
| Bytes | shared immutable storage | cheap slicing, hidden representation | Arc, Cow | high |
| HTTP | protocol values independent of I/O | generic body, deferred builder errors | Reqwest builder | very high in lineage |
| Regex | borrowed structure from dynamic text | compile-once object, optional match | parser combinators | high |
| Thiserror | inspectable library error contract | derive, sources, enum evolution | Anyhow | medium |
| Anyhow | contextual application error chain | type erasure, downcasting | Thiserror | medium |
| Tempfile | ownership-driven cleanup | Drop, persistence handoff | guards | high |
| Tower | policy composition around services | backpressure, generic middleware | Axum, Hyper | very high in lineage |
| Tracing | instrumentation separated from collection | spans, structured fields | logging APIs | high |
| Tokio | racing and cancellation through futures | macros, drop safety, task ownership | Futures | very high |
| Reqwest | staged asynchronous operation | builder, Serde, response policy | HTTP, Hyper | complete deep dive |
Empty primary lessons
These are candidates because the current atlas does not yet represent their main consumer-facing idea.
| Missing lesson | Strong candidate libraries | What would make the specimen distinct? |
|---|---|---|
| Validated domain types | URL, UUID, Semver, Time | parse once, then expose domain operations |
| Non-UTF-8 text | bstr, OsStr, paths | avoid promising Unicode where bytes are valid |
| Ordered associative collections | IndexMap | map vocabulary plus stable insertion order and indices |
| Graph identity and traversal | Petgraph | typed node indices separated from stored weights |
| Parser composition | Winnow, Nom | small parsers as values that combine and return structured errors |
| Capability guards | Mutex, Parking Lot | possession of a guard grants temporary access and cleanup |
| Read-mostly shared configuration | ArcSwap | cheap snapshots without holding a read lock |
| Compile-time checked queries | SQLx | external schema knowledge reflected in generated Rust types |
| Property-based input spaces | Proptest | generators and shrinkers composed as strategies |
| Forward-compatible flag sets | Bitflags | named set operations over compact unknown-tolerant bits |
| Typestate configuration | Rustls | configuration stages expose only valid next operations |
| Inline-storage policy | SmallVec | collection vocabulary with representation-dependent performance |
| Pin projection | Pin Project | macro creates safe access to structurally pinned fields |
| Scoped threads | Crossbeam | threads may borrow stack data when scope proves their lifetime |
| Format-preserving syntax trees | Syn + Quote | parse Rust syntax, transform typed nodes, emit tokens |
Overlap rules
A candidate becomes a full specimen when it satisfies all three conditions:
- Its primary lesson is absent or materially sharper than the current entry.
- A complete program can demonstrate that lesson without large scaffolding.
- The failure or tradeoff boundary is interesting enough to analyze.
Otherwise it becomes a comparison:
- Itertools belongs beside Iterator and Rayon unless an adaptor exposes a new extension-trait or ownership lesson.
- Hyper does not need a second fluent-request specimen; it belongs in the HTTP lineage as the lower-level connection and streaming boundary.
- Nom and Winnow should initially share one comparative parser-combinator entry.
- Parking Lot should be compared with
std::sync::Mutex, not praised merely for offering another lock. - UUID, URL, Semver, and Time can begin as one “validated domain values” page; only their distinct operations should determine later deep dives.
Prioritization rubric
Score potential additions from 0–2 on each dimension:
| Dimension | 0 | 1 | 2 |
|---|---|---|---|
| Ecosystem relevance | niche/internal | established | foundational/directly widespread |
| Concept novelty | duplicates atlas | sharper variation | empty primary lesson |
| Consumer clarity | heavy setup | understandable | compelling small program |
| Failure insight | little boundary | ordinary error | instructive compile/runtime boundary |
| Source trail | inaccessible/noisy | traceable | documented and locally inspectable |
| Tradeoff depth | mostly convenience | real compromise | competing representations worth debating |
The score prioritizes research; it does not declare a library objectively better. A lower-reach library with a uniquely expressive contract can still be the best teaching specimen.
Evidence status
All current atlas programs compile under Rust 1.91.0 and use versions pinned by
the repository’s Cargo.lock. Their stdout was captured during the book build
review. Boundary behavior is derived from public contracts and should be
verified with a dedicated negative example before a specimen is promoted to a
source-level deep dive.