hammer/docs/plan-variantes-cpu.md

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 (2026-07-17, laptop TigerLake, clang 3 variantes base/v3/v4, corpus 200MB mixto fuente+binarios):
  • zstd: v3/v4 NO pagan — CORTADO de la lista. Bench interno (-b3 -i7, estable): base 144.2 vs v4 146.5 MB/s comprimiendo, 702 vs 692 descomprimiendo = ruido. Causa conocida: zstd ya hace dispatch BMI2/AVX2 en runtime ⇒ el -march del build casi no toca los kernels calientes. (Un +24% aparente de v4 en la 1ª tanda desapareció con i7: era calentamiento — lección para T6: sólo benchs con control de varianza.)
  • zlib (madler): INCONCLUSO en laptop con carga (el mismo binario base osciló 112–157 MB/s entre tandas). Pero la pregunta estaba mal hecha: la respuesta buena no es una variante v3 de zlib sino zlib-ng (fork con SIMD y dispatch en runtime, drop-in ABI; Fedora 40 ya lo adoptó como zlib del sistema) ⇒ un solo artefacto, cero maquinaria de variantes. Candidato a receta; medir zlib-ng vs zlib en máquina quieta cuando toque.
  • Consecuencia estructural: los compresores modernos ya resuelven esto con dispatch interno ⇒ la lista caliente de variantes se concentra donde NO hay dispatch: mesa (llvmpipe/ACO compilan según -march) y códecs sin runtime-detect. El mecanismo T1–T4 sigue válido pero su primer cliente real es mesa, no la dupla zlib/zstd.
• 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.