sergio/takana

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

diff --git a/docs/plan-variantes-cpu.md b/docs/plan-variantes-cpu.md
new file mode 100644
index 00000000..0de59a7d
--- /dev/null
+++ b/docs/plan-variantes-cpu.md
@@ -0,0 +1,84 @@
+# Plan — variantes por nivel de CPU (x86-64-v3) sobre el CAS
+
+**Fecha:** 2026-07-16 · **Origen:** el linaje Solus (hwcap dirs AVX2 ~2017, lista corta medida)
+→ Red Hat (niveles x86-64-v2/v3/v4 + `glibc-hwcaps` en glibc 2.33, selección en el loader)
+→ CachyOS (repos enteros v3/v4 + LTO + scheduler). Análisis de qué forma toma eso en hammer.
+
+**Tesis:** hammer ya tiene la mitad difícil gratis. Una variante optimizada no es un mecanismo
+nuevo: es **la misma receta con otros `flags`**, que sella a otro hash en el mismo store. Lo que
+las distros binarias resuelven con subdirectorios mágicos del loader, hammer lo resuelve con lo
+que ya es: contenido direccionado por hash + hydrate.
+
+---
+
+## 1. La restricción que ordena todo el diseño: musl no tiene hwcaps
+
+El mecanismo `glibc-hwcaps` es del loader de **glibc**. El ldso de musl no busca en
+subdirectorios por microarquitectura y no va a hacerlo. Conclusión estructural:
+
+> **La selección de variante en hammer ocurre en HYDRATE (por máquina), no en runtime (por
+> proceso).** Cada máquina hidrata la variante que su CPU soporta; el árbol instalado tiene UNA
+> copia de cada lib, la correcta. Sin dispatch, sin dobles copias en disco, sin loader parcheado.
+
+Esto no es una limitación disfrazada: es el modelo más simple de los dos, y el único compatible
+con el resto de hammer (un artefacto = un hash = un contenido; "elige en runtime" rompería la
+correspondencia instalado↔sellado que usa todo, del journal a CVE-por-grafo).
+
+Costo honesto: una imagen/USB "para cualquier máquina" debe llevar baseline (o dos hydrates).
+El punto de selección es `hammer hydrate` / el instalador, con sonda de CPU (`cpuid` → nivel).
+
+## 2. Mecanismo: variante = flags, cero framework nuevo
+
+Hoy el sandbox fija `CC="zig cc -mcpu=baseline"` (`sandbox.rs:415`) precisamente para NO hornear
+la ISA del builder. Una variante v3 es el mismo contrato con otro valor pineado:
+
+- **T1 — campo `variant` en la receta** (o sección `[variants.v3]` que sólo sobreescribe
+  `flags`/`mcpu`). Regla dura: la variante **hereda todo lo demás** de la receta canónica —
+  misma fuente, mismos patches, mismas deps. Si diverge en algo más, no es una variante, es
+  otra receta.
+- **T2 — `mcpu=x86_64_v3` pineado por nombre de nivel**, nunca `native` (mismo argumento que
+  baseline: la ISA del builder no puede filtrarse; el nivel es el contrato).
+- **T3 — el índice firmado publica `(nombre, versión, nivel, hash)`**. El nivel es un eje más
+  del catálogo, no un repo aparte (donde CachyOS mantiene N repos, hammer tiene N hashes).
+- **T4 — sonda de nivel en hydrate/instalador**: detectar v2/v3/v4 y resolver el hash
+  correspondiente, con fallback a baseline. Idempotente como todo hydrate.
+
+La bit-repro no se toca: la reproducibilidad es por-(receta, flags); una variante v3 reproduce
+contra sí misma en la granja exactamente igual que hoy reproduce baseline.
+
+## 3. Alcance: lista caliente (Solus), NO repo entero (CachyOS)
+
+Recompilar el catálogo entero por nivel multiplica la granja por N para ganancias que en el 90%
+de los paquetes son ruido. Solus lo midió hace una década: el beneficio se concentra en un
+puñado de libs con kernels vectorizables. Lista caliente inicial (todas ya en el catálogo):
+
+| candidata | por qué |
+|---|---|
+| `zlib`, `zstd`, `xz` | (de)compresión en cada operación del propio hammer |
+| `mesa` | el caso con más ganancia medible en GUI/juegos (llvmpipe/ACO vectorizan) |
+| códecs (ffmpeg-clase, cuando entren) | el caso clásico AVX2 |
+| `pixman`, `cairo` | raster 2D — **frontera GUI: sólo en worker** (gotcha zig-skew) |
+
+- **T5 — piloto medido**: v3 de `zlib` + `zstd`, benchmark antes/después con carga real de
+  hammer (pack/hydrate de N artefactos). Si la ganancia no es medible ahí, la lista se corta
+  temprano y barato.
+- **T6 — regla de admisión**: una lib entra a la lista caliente con benchmark que lo
+  justifique, no por vibras. La lista vive en el repo junto a los números.
+
+## 4. Lo que NO se hace
+
+- **Repo entero v3/v4** — coste de granja ×N por ganancia marginal fuera de la lista caliente.
+- **Dispatch en runtime / hwcaps** — no existe en musl y el modelo por-máquina es mejor para
+  hammer de todos modos (§1).
+- **`-mcpu=native` jamás** — ni en variantes: el nivel nombrado es el contrato reproducible.
+- **LTO generalizado como campaña** — hammer ya linkea estático con zig; el LTO por-receta se
+  evalúa donde el benchmark de T5/T6 lo pida, no como política global.
+
+## Orden propuesto
+
+1. **T5** (piloto zlib/zstd en worker, benchmark) — decide si el frente vale antes de tocar
+   framework.
+2. **T1–T2** (campo variant + mcpu pineado) — sólo si T5 da ganancia medible.
+3. **T3–T4** (índice + sonda en hydrate) — cierra el ciclo usable.
+4. **mesa v3** — el premio gordo para juegos; coordinar con el plan de jaula de juegos
+   (`plan-jaula-juegos.md`), siempre en worker.