From 5851e5ded0ad6b2b9aee5947c675623dcdb864e4 Mon Sep 17 00:00:00 2001
From: Joel Alvarez <jeresoft@gmail.com>
Date: Tue, 28 Jul 2026 13:11:27 -0700
Subject: [PATCH] docs: specify async channels

---
 docs/design/09-canales-y-sincronizacion.md    | 53 +++++++++++++++++++
 .../plans/2026-07-28-rust-async-course.md     |  1 +
 2 files changed, 54 insertions(+)
 create mode 100644 docs/design/09-canales-y-sincronizacion.md

diff --git a/docs/design/09-canales-y-sincronizacion.md b/docs/design/09-canales-y-sincronizacion.md
new file mode 100644
index 0000000..18e56d8
--- /dev/null
+++ b/docs/design/09-canales-y-sincronizacion.md
@@ -0,0 +1,53 @@
+# Diseño: Canales y Sincronización Asíncrona
+
+**Curso:** Rust Async · **Capítulo:** 09 · **Estado:** draft
+
+Un canal transfiere la propiedad de mensajes entre tareas sin obligarlas a
+esperar en el mismo instante. El productor y el consumidor conservan ritmos
+independientes; la capacidad del canal decide cuántos mensajes puede absorber
+la cola antes de ejercer presión hacia el productor.
+
+## Problema
+
+Compartir una colección mutable entre tareas acopla la coordinación a su
+bloqueo y a la vida de la estructura compartida. Un canal expresa una frontera
+más clara: un emisor entrega mensajes y un receptor decide cuándo procesarlos.
+La elección no elimina el costo de coordinación; lo hace visible mediante
+capacidad, espera, cierre y pérdida potencial de mensajes.
+
+## Alternativas
+
+- Un canal acotado aplica *backpressure*: cuando la cola se llena, `send`
+  espera hasta que exista capacidad o el receptor cierre el canal.
+- Un canal no acotado evita esa espera del emisor, pero puede acumular memoria
+  sin límite útil; no es la opción predeterminada para un sistema con carga
+  desconocida.
+- Una estructura compartida con `Mutex` puede ser apropiada para estado
+  compartido, pero no comunica por sí sola propiedad, cierre ni orden de
+  consumo.
+- Un `watch` o una señal de cancelación modelan el último estado, no una cola
+  de todos los mensajes; no deben sustituir un canal cuando cada evento importa.
+
+## Invariantes
+
+1. En el modelo acotado, la cola nunca excede su capacidad declarada.
+2. Cada mensaje aceptado se entrega como máximo una vez a un receptor.
+3. El orden FIFO se garantiza dentro de un único canal y un único receptor;
+   varios receptores o prioridades requieren un contrato diferente.
+4. Al cerrarse todos los emisores, el receptor puede drenar lo pendiente y
+   después observa el cierre de forma explícita.
+5. Al cerrar el receptor, un emisor pendiente recibe un error; no se finge que
+   el mensaje fue entregado.
+6. La sincronización no debe depender de `sleep`: las pruebas usarán señales y
+   resultados observables del canal.
+
+## Decisión Educativa
+
+El modelo siguiente usará `tokio::sync::mpsc::channel` con una capacidad
+pequeña y mensajes enteros. Esto permite demostrar presión de cola, cierre del
+emisor y cierre del receptor con resultados deterministas, sin introducir
+`unsafe` ni abstraer el protocolo real detrás de una API inventada.
+
+Un capítulo posterior comparará este límite con el modelo de actores: el canal
+es la tubería; el actor agrega propiedad de estado, protocolo de mensajes y
+ciclo de vida.
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 7e1b171..a3fcdab 100644
--- a/docs/superpowers/plans/2026-07-28-rust-async-course.md
+++ b/docs/superpowers/plans/2026-07-28-rust-async-course.md
@@ -76,6 +76,7 @@ Para cada capítulo, antes de pasar al siguiente:
   - [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.
+  - [x] #29 Especificar backpressure, cierre y sincronización.
 
 ### Milestone 4: Composición avanzada