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