Appendix T — Source Map and Further Reading

A source map is useful only when it can stop a claim from quietly becoming stronger than its evidence.

At the end of a long-lived Rust manuscript, “the docs say” is not an adequate citation policy. Which documentation: a language reference, a standard-library contract, a Cargo command page, an accepted design RFC, a compiler-team guide, a runtime’s latest crate docs, or a blog post? Which version? Was the claim promised, observed, recommended, or merely conventional? What must be rerun when the compiler, target, dependency, or operating environment changes?

This appendix is the evidence ledger for those questions. It establishes a versioned official-source map, routes RFCs to their proper historical and design role, inventories third-party sources per manuscript unit, and records claims whose truth depends on current implementation behavior. The generated catalog at examples/rust-engineering-handbook/appendices/source-map-audit/source-inventory.json contains every Markdown source link found across all 99 numbered chapters and 20 appendices. Its verifier checks coverage and classification. It does not decide whether an author’s interpretation is correct.

Put the claim above the link

The evidence path runs in one direction:

claim and classification
        │
        ├──> controlling source + version/snapshot
        │          │
        │          └──> reproducer + complete environment, when behavior is observed
        │                            │
        └──> product policy <────────┘
                    │
                    └──> recheck trigger + owner + retained artifact

A URL without a claim is a reading suggestion. A compiler transcript without environment metadata is an anecdote. A documented mechanism without product policy cannot decide whether a change is acceptable. For example, Cargo can document how rust-version influences resolution; only the library’s declared policy says what MSRV it supports, and only the test matrix supplies evidence for that promise.

Record each consequential claim with this minimum packet:

Do not combine several independently falsifiable statements under one claim ID. “This is safe and fast on supported platforms” needs at least a safety argument, performance experiment, platform matrix, and definition of “supported.”

Resolve disagreement by authority and scope

Begin with the source that owns the contract. For language and standard-library claims, that is the Rust Reference or the relevant library documentation, within their stated completeness and stability bounds. For Cargo, rustc, rustdoc, editions, rustfmt, Clippy, or rustup, use the corresponding official tool book. For a pinned crate, runtime, operating system, platform, or standard, use the maintainer or standards body’s documentation; its authority stops at that boundary.

Accepted RFCs and official project design notes explain motivation and approved design, but they may precede implementation changes, stabilization adjustments, or later amendments. Pair them with current documentation. The Rustonomicon and other official unsafe-code guidance provide essential expert direction while openly leaving parts of aliasing and provenance incomplete. High-quality secondary material can explain, teach, or lead you to a source; it should not become the authority for a normative claim owned elsewhere.

Reproduced compiler or tool behavior answers a different question: what did this named version do in this environment? Preserve a minimal reproducer whenever the claim is observational or when behavior appears to disagree with documentation. The result may reveal an implementation fact or a defect, but it does not manufacture a stable guarantee; retain it and escalate the disagreement rather than silently choosing whichever evidence is more convenient.

Scope decides the route. The Reference cannot define Tokio’s spawn cancellation behavior; Tokio’s documentation cannot weaken Future::poll; a benchmark guide cannot predict relay-service latency; and a current compiler result cannot override a documented promise without review.

Version baseline for this manuscript snapshot

The official Rust 1.97.0 release announcement and detailed release notes establish the editorial snapshot. Stable documentation URLs intentionally float to the current stable channel. Therefore the inventory records both the canonical URL and capture date. When exact historical wording or behavior matters, archive the relevant evidence under the project’s retention policy or use version-specific documentation where the Rust project publishes it; do not assume a floating URL preserves old text.

This source map does not retroactively validate earlier chapter statements that say their fixtures ran on Rust 1.97.0 or 1.85.0. Those statements belong to retained execution evidence and require their own audit. The source map identifies where to look and what should trigger a rerun.

Official-source map

Language, semantics, and standard library

Use the Reference for “what form and behavior is defined,” standard docs for “what this API requires and promises,” and the Book for “how the pieces fit.” A chapter may cite all three when they perform different jobs.

Cargo, compiler, documentation, style, and diagnostics

Unsafe code, APIs, and async project guidance

The source class should appear in the prose when misunderstanding is costly: “the Reference guarantees,” “the standard library documents,” “the compiler guide describes the current implementation,” or “the handbook recommends.” Avoid the flattening phrase “Rust says.”

RFC map: design history, not a substitute for stabilized behavior

An accepted RFC records a design decision at a point in project history. It can explain why a feature exists and which alternatives were considered. It may precede implementation changes, stabilization adjustments, terminology changes, later RFCs, or Reference wording. For production decisions, pair the RFC with current documentation and compiler/MSRV evidence.

This is a routing index, not a complete RFC bibliography. Add an RFC when the design history materially explains a choice or compatibility edge. Do not add RFC links merely to make a source list look deep.

The per-unit inventory exposes third-party dependencies

source-inventory.json is generated from Markdown links rather than maintained as a second hand-written bibliography. Each record includes unit key, title, manuscript file, label, URL, hostname, and source class:

• official-rust for doc.rust-lang.org and blog.rust-lang.org;
• rust-project-guidance for Rust project books/sites such as rust-lang.github.io and the compiler development guide;
• third-party for crate documentation, platforms, standards, security bodies, operating-system manuals, and secondary sources.

The generator excludes literal demonstration hosts such as example.invalid and URLs that appear only as code data rather than Markdown citations. It rejects unknown source classes rather than silently calling them official. The exact third-party records remain attached to their chapters, which prevents this summary from aging into a false catalog.

The current manuscript’s important third-party source families include:

A standards document can be primary for its standard while still being third-party relative to Rust. “Third-party” is not a quality judgment. It identifies who owns the contract and what version must be pinned.

Run the inventory after any chapter-source change:

node examples/rust-engineering-handbook/appendices/source-map-audit/build-source-inventory.mjs
node examples/rust-engineering-handbook/appendices/source-map-audit/verify.mjs

The first command regenerates the JSON from manuscript source. The second asserts 99 numbered chapters, Appendices A–T, classified citations, no demonstration URL leakage, an exact declaration of any unit with no Markdown citation, and complete current-implementation records. The current scan contains one explicit source-free integration unit: Chapter 93. Its evidence notes route readers to four repository fixtures and delimit those results rather than making an externally sourced mechanism claim, so the inventory retains the absence as a visible exception instead of inventing a citation. Any future external mechanism, platform, or policy claim added there must supply its own controlling source. A green result proves structural catalog coverage and honest exception reporting, not link availability, claim accuracy, source quality, or faithful interpretation.

Register current-implementation behavior explicitly

Implementation observations are valuable when the question is inherently empirical. They become dangerous when their environment disappears. The generated artifact carries the following register:

Each record is deliberately a family, not a claim that every routed chapter has identical evidence. A chapter-level claim should reference the family ID and add the exact observation. If the environment cannot be reconstructed, narrow or remove the claim.

Example implementation record

{
  "claimId": "CI-007-relay-cancel-01",
  "classification": "third-party-behavior",
  "claim": "Dropping the caller future does not cancel the separately spawned flush task in this adapter design.",
  "scope": {
    "runtime": "named runtime and pinned version",
    "features": ["declared feature set"],
    "target": "x86_64-unknown-linux-gnu",
    "adapterRevision": "retained source revision"
  },
  "authority": ["runtime spawn/join documentation", "Future::poll contract"],
  "reproduction": "deterministic barrier test that drops the caller before releasing flush",
  "retainedEvidence": ["test source", "lockfile", "command", "event trace"],
  "residualRisk": "does not establish fairness, production timing, or behavior on another runtime",
  "recheckTrigger": ["runtime update", "feature change", "task ownership change", "target change"],
  "owner": "async subsystem owner"
}

The same observed event can support different policy decisions. One API may specify that accepted work continues after caller cancellation and provide idempotent result discovery. Another may guarantee revocation before commit. The source packet establishes what the chosen implementation does; the public contract and product policy determine whether that behavior is acceptable.

Worked source packet: future, task, runtime, and cancellation

Consider the claim: “Awaiting a write runs it on a background thread, and timeout cancels it.” Audit it as four separate propositions.

1. What is guaranteed by Future? The standard-library Future::poll contract defines polling, Pending, Ready, and wakeup expectations. It does not promise a background thread, a runtime, I/O completion, fairness, or cancellation of external work. Classification: guarantee, limited to the trait contract.

2. What does .await contribute? The language desugaring and official Async Book primer explain that awaiting polls a future and permits suspension rather than blocking the current thread in the ordinary model. Awaiting two operations sequentially does not itself spawn either operation. Classification: language/project explanation, checked against current Reference/compiler behavior where exact desugaring matters.

3. Where is the task scheduled? A named runtime API may spawn a future as a task and may require Send, permitting movement among worker threads. A local executor may keep it on one thread. The runtime’s pinned documentation and configuration control this claim. Classification: third-party behavior or current implementation, depending on what the runtime promises.

4. What does timeout cancel? A timeout combinator may drop a child future, return an error while external I/O continues, signal a task, abort a runtime task, or merely stop the caller waiting. The answer requires the exact combinator, future drop contract, child-task ownership, external effect, commit point, and deterministic evidence. Classification: usually a combination of third-party behavior and application contract.

The corrected statement becomes something like:

upload().await polls the returned future within the caller’s current task; it does not spawn by itself. In adapter version X with features Y, start_flush separately spawns an owned flush future under the named runtime. The timeout branch drops only the caller’s response future. The flush task continues to its documented commit point, and the service joins it during shutdown. The public API therefore requires an idempotency key and result query after timeout.

The correction can be accepted only after X, Y, the runtime authority, retained test, and public contract are real. Symbolic identifiers are appropriate in this worked template because it is not claiming behavior for a specific dependency; a production record must replace them.

Further reading by engineering job

Reading lists should follow the decision the reader must make, not a prestige ranking.

Language and ownership decisions. Begin with the Book for the integrated model, then use the Reference chapters on expressions, patterns, types, destructors, and behavior plus standard-library contracts. Use Appendices A–H as retrieval aids and the Reference/std pages they cite as authority.

Public library and compatibility decisions. Use Cargo’s SemVer, features, resolver, packaging, and rust-version documentation; the Edition Guide; rustdoc; API Guidelines; Chapters 45–51; and Appendices I, J, Q, and R. Add credible downstream witnesses. An API diff is inventory evidence, not the release decision.

Concurrency and async decisions. Use standard thread, atomics, Future, task, Pin, and Waker documentation; Reference memory rules; the Async Book; Chapters 52–65; and Appendices M and N. Then add the pinned runtime’s own documentation and deterministic lifecycle evidence.

Unsafe, FFI, and representation decisions. Use the Reference, std::ptr, type and API safety sections, the Rustonomicon with its limitations, target/ABI authorities, Chapters 66–74, and Appendices K and L. Retain a safety case; Miri, sanitizers, fuzzing, and target tests cover named defect classes but do not prove soundness.

Performance and production decisions. Use standard/Cargo/rustc contracts for mechanism, then primary tool/platform documentation and representative local measurement. Chapters 84–93 and Appendices O and P organize the experiment, operational, and security evidence. Secondary performance guides can suggest methods, never substitute for the workload.

Long-term stewardship. Use release notes, the Edition Guide, Cargo policy documentation, target support pages, advisory/provenance standards, Chapters 94–99, and Appendices Q–T. Schedule source refresh alongside toolchain, MSRV, dependency, platform, and policy review.

Exercise: audit a source packet before it enters policy

A team proposes this compatibility note:

On stable Rust, relay-service futures are two pointers, Tokio tasks are fair, resolver 3 always selects MSRV-compatible dependencies, Miri proves the unsafe ring buffer sound, and a passing benchmark shows the new version is faster.

Produce an evidence ledger that:

1. splits the sentence into independently falsifiable claims;
2. classifies each as guarantee, current implementation, convention, recommendation, experimental/unstable, or third-party behavior;
3. identifies the strongest applicable official or third-party source and its version;
4. rejects or narrows any universal that the source does not promise;
5. defines a reproducer with compiler, Cargo, edition, target, profile, features, lockfile, dependency versions, hardware/OS, and command where relevant;
6. states what each observation fails to prove;
7. routes unsafe soundness, runtime fairness, dependency policy, and performance claims to the correct independent reviewer;
8. defines recheck triggers and evidence-retention paths;
9. chooses whether each claim may enter public API policy, internal design documentation, a benchmark report, or nowhere yet.

A defensible result will reject “Miri proves soundness” and “one benchmark proves faster.” It may retain narrower evidence: Miri found no modeled violation across a specified test set on a pinned nightly, and a representative benchmark showed a measured distribution under one controlled environment. It will treat future layout as an observation only when there is a reason to care about size or retention, and it will source resolver behavior to the named Cargo release without converting selection assistance into compatibility proof.

Source-maintenance card

Before a manuscript or policy refresh closes, confirm:

• Every consequential claim has one classification and one controlling scope.
• Official language, std, and tool sources are not flattened into generic “Rust docs.”
• Accepted RFCs are paired with current stabilized documentation and compiler/MSRV evidence.
• Every third-party claim names a dependency, platform, tool, or specification version.
• Current-implementation observations retain source, commands, inputs, environment, output, residual risk, and recheck trigger.
• Compiler release, language edition, package version, MSRV, stable channel, target, profile, and feature set are not conflated.
• Link availability has not been mistaken for source authority or correct interpretation.
• Tests and tools are credited only for the defect classes and configurations they exercise.
• Product policy makes the acceptance decision; mechanisms and measurements inform it.
• The generated inventory passes, and a qualified reviewer still reads the claims.

The last source in the chain is not the end of the argument. It is the point where another engineer can reproduce, challenge, narrow, or update the claim without guessing what the author meant.

Sources and version notes

• The official source set and authority order derive from the handbook outline and are anchored in the Rust Reference, standard library, Cargo Book, Edition Guide, rustc book, rustdoc book, Style Guide, Clippy, Rustonomicon, API Guidelines, and Async Book.
• The editorial snapshot is Rust 1.97.0, announced by the Rust Release Team on 2026-07-09. The recorded local host exposed Rust/Cargo 1.93.1; no unavailable 1.97.0 execution is claimed.
• source-inventory.json is a dated structural catalog generated from manuscript Markdown. It does not archive source content, prove that a URL will remain stable, validate external claims, or grant release authority.

Source classifications and version records are evidence inputs, not release authority. A qualified subject-matter reviewer still owns the decision to accept, narrow, reproduce, or reject the claim.