From a5590b9604d8c78ec430b0da702ae91bb350f152 Mon Sep 17 00:00:00 2001
From: Joel Alvarez <jeresoft@gmail.com>
Date: Tue, 28 Jul 2026 13:09:44 -0700
Subject: [PATCH] docs: add select cancellation chapter

---
 diagrams/08-select-timeouts.mmd               |  4 ++
 docs/08-select-cancelacion-y-timeouts.md      | 42 +++++++++++++++++++
 .../plans/2026-07-28-rust-async-course.md     |  4 +-
 examples/select_timeout_basic.rs              | 10 +++++
 4 files changed, 58 insertions(+), 2 deletions(-)
 create mode 100644 diagrams/08-select-timeouts.mmd
 create mode 100644 docs/08-select-cancelacion-y-timeouts.md
 create mode 100644 examples/select_timeout_basic.rs

diff --git a/diagrams/08-select-timeouts.mmd b/diagrams/08-select-timeouts.mmd
new file mode 100644
index 0000000..5c0b8bf
--- /dev/null
+++ b/diagrams/08-select-timeouts.mmd
@@ -0,0 +1,4 @@
+flowchart LR
+    S[select!] --> A[Rama preparada]
+    S --> B[Otras ramas pendientes]
+    T[timeout] --> O[Éxito o expiración]
diff --git a/docs/08-select-cancelacion-y-timeouts.md b/docs/08-select-cancelacion-y-timeouts.md
new file mode 100644
index 0000000..185e932
--- /dev/null
+++ b/docs/08-select-cancelacion-y-timeouts.md
@@ -0,0 +1,42 @@
+# select!, Cancelación y Timeouts
+
+> **Curso:** Rust Async · **Capítulo:** 08 · **Código:** `src/coordination.rs` · **Estado:** draft
+
+## Introducción
+
+`select!` permite reaccionar a la primera operación preparada. Los timeouts
+hacen explícito cuánto se acepta esperar; cancelar exige que cada punto de
+suspensión conserve invariantes válidas.
+
+## Fundamentos
+
+Una rama ganadora no demuestra que las demás terminaron. Un timeout devuelve
+éxito o expiración, no una conclusión sobre la causa del retraso. Al soltar un
+future pendiente puede ocurrir cancelación, por lo que la operación debe ser
+segura de abandonar.
+
+```mermaid
+flowchart LR
+    S[select!] --> A[Rama preparada]
+    S --> B[Otras ramas pendientes]
+    T[timeout] --> O[Éxito o expiración]
+```
+
+## Modelo y Límites
+
+El modelo usa una rama inmediata y otra pendiente para que el resultado sea
+determinista. No pretende afirmar equidad del macro ni modelar cancelación de
+recursos externos.
+
+```rust
+assert_eq!(rust_async::coordination::first_ready().await, "immediate");
+```
+
+## Ejercicios y Referencias
+
+1. Añade una tercera rama pendiente.
+2. Distingue timeout de error de aplicación.
+3. Diseña una operación cancelable por etapas.
+4. Explica por qué ganar `select!` no cancela automáticamente todo recurso.
+
+Referencia: [tokio::select!](https://docs.rs/tokio/latest/tokio/macro.select.html).
diff --git a/docs/superpowers/plans/2026-07-28-rust-async-course.md b/docs/superpowers/plans/2026-07-28-rust-async-course.md
index 24d0450..7e1b171 100644
--- a/docs/superpowers/plans/2026-07-28-rust-async-course.md
+++ b/docs/superpowers/plans/2026-07-28-rust-async-course.md
@@ -73,8 +73,8 @@ Para cada capítulo, antes de pasar al siguiente:
   - [x] #25 Escribir capítulo, comparativas, ejemplos y ejercicios.
 - [ ] Capítulo 08: `select!`, cancelación y timeouts.
   - [x] #26 Especificar garantías y alternativas.
-  - [ ] #27 Implementar y probar modelos deterministas.
-  - [ ] #28 Escribir capítulo, diagrama, ejemplos y ejercicios.
+  - [x] #27 Implementar y probar modelos deterministas.
+  - [x] #28 Escribir capítulo, diagrama, ejemplos y ejercicios.
 - [ ] Capítulo 09: canales y sincronización asíncrona.
 
 ### Milestone 4: Composición avanzada
diff --git a/examples/select_timeout_basic.rs b/examples/select_timeout_basic.rs
new file mode 100644
index 0000000..a375f3e
--- /dev/null
+++ b/examples/select_timeout_basic.rs
@@ -0,0 +1,10 @@
+#[tokio::main]
+async fn main() {
+    assert_eq!(rust_async::coordination::first_ready().await, "immediate");
+    assert_eq!(
+        rust_async::coordination::immediate_with_timeout()
+            .await
+            .expect("operation should finish"),
+        1
+    );
+}