Add full mdBook content for Rust at the Limit

Twelve chapters covering lifetimes, variance, HRTB, async internals,
async lifetimes, Pin, async traits, error messages decoded, working
patterns, and the two cases of compiler/programmer disagreement.

Includes book.toml, GitHub Pages deploy workflow (peaceiris/actions-mdbook),
README, bibliography, and CC0 license page.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: DavidLiedle

.github/workflows/deploy.yml

@@ -0,0 +1,49 @@
+name: Deploy mdBook to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v2
+        with:
+          mdbook-version: 'latest'
+
+      - name: Build book
+        run: mdbook build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./book
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,2 @@
+book/
+.DS_Store

README.md

@@ -0,0 +1,46 @@
+# Rust at the Limit
+
+**The four corners of Rust where ordinary intuition stops working.**
+
+**[Read online at cloudstreet-dev.github.io/Rust-at-the-Limit](https://cloudstreet-dev.github.io/Rust-at-the-Limit/)**
+
+## About This Book
+
+Async, lifetimes, `Pin`, higher-rank trait bounds, variance — the parts of Rust where the type system stops feeling helpful and starts feeling like an antagonist.
+
+This book is for engineers who have already cleared the borrow checker and hit the next wall. The error messages are paragraphs long. The type system has opinions about variance that they don't share. Async functions silently impose constraints they didn't sign up for. `Pin` exists.
+
+The book takes the reader into that territory deliberately, with a guide rather than a tutorial. Tone is direct, technical, occasionally sympathetic, never condescending.
+
+## Table of Contents
+
+### Part I: The Type System's Edges
+- [Past the Borrow Checker](src/introduction.md)
+- [Lifetimes Are Not What You Think](src/ch01-lifetimes.md)
+- [Variance](src/ch02-variance.md)
+- [Higher-Rank Trait Bounds](src/ch03-hrtb.md)
+
+### Part II: Async, From the Inside
+- [Async Internals](src/ch04-async-internals.md)
+- [Async and Lifetimes Collide](src/ch05-async-lifetimes.md)
+- [Pin and Why It Has To Exist](src/ch06-pin.md)
+- [The Async Trait Problem](src/ch07-async-trait.md)
+
+### Part III: Survival
+- [Error Messages, Decoded](src/ch08-error-messages.md)
+- [Patterns That Work](src/ch09-patterns.md)
+
+### Part IV: Disagreement
+- [When the Type System Is Right and You're Wrong](src/ch10-compiler-right.md)
+- [When the Type System Is Wrong and You're Right](src/ch11-escape-hatches.md)
+
+## Building Locally
+
+```sh
+cargo install mdbook
+mdbook serve --open
+```
+
+## License
+
+CC0 1.0 Universal — public domain dedication. Take it, fork it, ship it, claim it as your own. See [LICENSE](LICENSE).

book.toml

@@ -0,0 +1,31 @@
+[book]
+title = "Rust at the Limit"
+authors = ["Claude Code"]
+description = "Async, lifetimes, Pin, higher-rank trait bounds, variance — the parts of Rust where the type system stops feeling helpful and starts feeling like an antagonist. A survival guide to the four corners of Rust where ordinary intuition stops working."
+language = "en"
+src = "src"
+
+[build]
+build-dir = "book"
+
+[output.html]
+git-repository-url = "https://github.com/cloudstreet-dev/Rust-at-the-Limit"
+edit-url-template = "https://github.com/cloudstreet-dev/Rust-at-the-Limit/edit/main/{path}"
+site-url = "/Rust-at-the-Limit/"
+default-theme = "navy"
+preferred-dark-theme = "navy"
+
+[output.html.fold]
+enable = true
+level = 0
+
+[output.html.search]
+enable = true
+limit-results = 30
+teaser-word-count = 30
+use-boolean-and = true
+boost-title = 2
+boost-hierarchy = 1
+boost-paragraph = 1
+expand = true
+heading-split-level = 3

src/SUMMARY.md

@@ -0,0 +1,33 @@
+# Summary
+
+[Past the Borrow Checker](introduction.md)
+
+---
+
+# Part I: The Type System's Edges
+
+- [Lifetimes Are Not What You Think](ch01-lifetimes.md)
+- [Variance](ch02-variance.md)
+- [Higher-Rank Trait Bounds](ch03-hrtb.md)
+
+# Part II: Async, From the Inside
+
+- [Async Internals](ch04-async-internals.md)
+- [Async and Lifetimes Collide](ch05-async-lifetimes.md)
+- [Pin and Why It Has To Exist](ch06-pin.md)
+- [The Async Trait Problem](ch07-async-trait.md)
+
+# Part III: Survival
+
+- [Error Messages, Decoded](ch08-error-messages.md)
+- [Patterns That Work](ch09-patterns.md)
+
+# Part IV: Disagreement
+
+- [When the Type System Is Right and You're Wrong](ch10-compiler-right.md)
+- [When the Type System Is Wrong and You're Right](ch11-escape-hatches.md)
+
+---
+
+[Bibliography and Sources](bibliography.md)
+[License](license.md)

src/bibliography.md

@@ -0,0 +1,67 @@
+# Bibliography and Sources
+
+The writing on the material in this book is mostly scattered: official documentation, RFCs, blog posts by Rust team members, and a few books. Here are the sources this book drew on, organized roughly by chapter.
+
+## Official documentation
+
+- *The Rust Programming Language* — [doc.rust-lang.org/book](https://doc.rust-lang.org/book/). The prerequisite. If anything in this book felt like it skipped the basics, the basics are here.
+- *The Rust Reference* — [doc.rust-lang.org/reference](https://doc.rust-lang.org/reference/). The formal description of the language. Dense, accurate, occasionally the only authoritative source for an obscure question.
+- *The Rustonomicon* — [doc.rust-lang.org/nomicon](https://doc.rust-lang.org/nomicon/). Subtitle: *The Dark Arts of Advanced and Unsafe Rust Programming*. Mostly about unsafe code, but the chapters on subtyping, variance, and lifetimes are the canonical references for chapters 1 and 2 of this book.
+- *Asynchronous Programming in Rust* — [rust-lang.github.io/async-book](https://rust-lang.github.io/async-book/). The official introduction to async. The chapter on the executor model and `Pin` is particularly good.
+
+## Posts by Rust team members and async working group
+
+- **Niko Matsakis** ([smallcultfollowing.com/babysteps](https://smallcultfollowing.com/babysteps/)) — the canonical source for type system internals. Posts on lifetime inference, HRTB, async traits, and the implementation of NLL (non-lexical lifetimes) are essential reading.
+- **Aaron Turon** ([aturon.github.io/blog](https://aturon.github.io/blog/)) — laid the foundation for Rust's async model in 2016. The posts on zero-cost futures, abstraction without overhead, and the design of trait objects are still relevant.
+- **Withoutboats** ([without.boats](https://without.boats/)) — the design history of `Pin`, the early thinking on async, and several posts on what the language could have been. Disagrees with later async direction in places; worth reading regardless.
+- **Ralf Jung** ([ralfj.de/blog](https://www.ralfj.de/blog/)) — the formal model of Rust's memory and aliasing. Stacked Borrows, Tree Borrows, and Miri all originate here. Essential if you write unsafe.
+- **Alice Ryhl** ([ryhl.io/blog](https://ryhl.io/blog/)) — practical async patterns. *Actors with Tokio* is the canonical reference for the actor pattern; *Async: What is blocking?* is the canonical reference for the blocking-vs-async distinction.
+- The [Rust async working group's vision document](https://rust-lang.github.io/wg-async/vision.html) — the roadmap for async Rust as of 2026.
+
+## Books
+
+- *Rust for Rustaceans* by Jon Gjengset (No Starch Press, 2021). The closest thing to a prerequisite for this book in print form. Covers async, lifetimes, and unsafe at the level of someone who is past the basics but not yet at the limits.
+- *Programming Rust* (2nd ed.) by Jim Blandy, Jason Orendorff, Leonora Tindall (O'Reilly, 2021). Comprehensive reference, treats lifetimes carefully, has a useful chapter on async.
+- *Zero To Production In Rust* by Luca Palmieri (self-published, ongoing). Async Rust applied to a real production system. Worth reading for the patterns it shows by example.
+
+## Videos
+
+- Jon Gjengset's [Crust of Rust](https://www.youtube.com/playlist?list=PLqbS7AVVErFiWDOAVrPt7aYmnuuOLYvOa) series — long-form livecoding walking through advanced Rust topics. The episodes on async, `Pin`, and lifetimes are excellent supplements to the corresponding chapters here.
+- The [RustConf](https://www.youtube.com/@rustvideos) talks on async internals from various years. Search for "async" plus "Niko Matsakis" or "Tyler Mandry" or "Eric Holk."
+
+## RFCs
+
+The relevant RFCs for the material in this book:
+
+- [RFC 0066](https://rust-lang.github.io/rfcs/0066-better-temporary-lifetimes.html) — temporary lifetimes.
+- [RFC 1214](https://rust-lang.github.io/rfcs/1214-projections-lifetimes-and-wf.html) — projections, lifetimes, and well-formedness.
+- [RFC 2349](https://rust-lang.github.io/rfcs/2349-pin.html) — `Pin`.
+- [RFC 2394](https://rust-lang.github.io/rfcs/2394-async_await.html) — `async`/`await` syntax.
+- [RFC 2592](https://rust-lang.github.io/rfcs/2592-futures.html) — the `Future` trait in `std`.
+- [RFC 3185](https://rust-lang.github.io/rfcs/3185-static-async-fn-in-trait.html) — `async fn` in traits, the static-dispatch case.
+- [RFC 3425](https://rust-lang.github.io/rfcs/3425-return-position-impl-trait-in-traits.html) — return-position `impl Trait` in traits.
+
+## Crates referenced
+
+- [`tokio`](https://docs.rs/tokio/) — the dominant async runtime.
+- [`async-trait`](https://docs.rs/async-trait/) — boxed-future trait macro.
+- [`trait-variant`](https://docs.rs/trait-variant/) — generates boxed variants of native async traits.
+- [`pin-project`](https://docs.rs/pin-project/) and [`pin-project-lite`](https://docs.rs/pin-project-lite/) — safe `Pin` projection.
+- [`bytemuck`](https://docs.rs/bytemuck/) — safe transmutation.
+- [`ouroboros`](https://docs.rs/ouroboros/) — self-referential structs without writing `unsafe`.
+- [`crossbeam`](https://docs.rs/crossbeam/) — lock-free data structures.
+- [`parking_lot`](https://docs.rs/parking_lot/) — faster `Mutex`/`RwLock` than `std`.
+- [`embassy`](https://embassy.dev/) — async runtime for embedded.
+
+## Where to go after this book
+
+This book is a survival guide. To go deeper, in roughly this order:
+
+1. Write more code in the patterns from chapter 9 until they are reflexive.
+2. Read the source of `tokio`, particularly the `task` and `sync` modules. Surprisingly readable.
+3. Read the source of `pin-project` to see what safe pin projection looks like in practice.
+4. Read Niko's blog backwards in time, starting from the most recent posts about async.
+5. Pick a small `unsafe`-using crate (`bytes`, `parking_lot`, or `crossbeam`) and read its `unsafe` blocks; check the safety comments against your understanding.
+6. Run Miri on your own code if you have any. Even if you don't have `unsafe`, Miri will catch some categories of bugs in dependencies.
+
+The material in this book gets internalized by use, not by reading. Write more code. Hit more walls. Each wall, eventually, becomes a door.