1# hammer
2
3> Una distribución Linux construida con un **laboratorio funcional y hermético** en el
4> sótano, y una **terminal mutable, clásica y anárquica** en el piso de arriba — diseñada
5> desde el suelo para que una **IA programadora** entienda, modifique y comparta el sistema.
6
7`hammer` no es otro gestor de paquetes inmutable. Es una arquitectura de dos mundos:
8
9- **El laboratorio** compila desde fuentes upstream (commits fijados), de forma
10  determinista y aislada (`bubblewrap` + `zig cc` + musl estático), y direcciona cada
11  artefacto por su hash (BLAKE3) en un *content-addressed store*.
12- **El userland** es un Linux clásico, mutable, con FHS de verdad (`/bin`, `/lib`, `/etc`).
13  Los binarios se **hidratan** desde el store por *hardlinks*. Puedes pisar archivos en
14  caliente, romper cosas con un `rm -rf`, y revertir cuando quieras.
15
16Entre ambos mundos viven las tres piezas que hacen a `hammer` distinto:
17
181. **Overlay de experimentación** — prueba cambios sobre el sistema real con red de
19   seguridad; `hammer try` / `commit` / `discard`.
202. **Diario de mutaciones** — un daemon `fanotify` registra todo lo que tú (o la IA)
21   cambiáis a mano. Vives imperativamente; el sistema genera el delta contra la base
22   limpia. **El diario es tu configuración — sin ser declarativa.**
233. **Manifiesto `.swm`** — compartes la *receta de la mutación* (parche de fuente + flags +
24   ediciones de config), no el binario cocinado. El receptor **reproduce y verifica**; no
25   confía en tu binario.
26
27Encima de todo corre el **bus de agente** (`/run/agent.sock`): la IA habla un protocolo
28pequeño y legible, dispara compilaciones, inyecta en el overlay, escucha fallos y reacciona.
29Tú tienes la última palabra.
30
31## Estado
32
33Fase de arranque. Validamos la capa AI-nativa **sobre Alpine** (musl + FHS ya cocidos)
34antes de bajar a distro propia. Ver [`docs/10-roadmap.md`](docs/10-roadmap.md).
35
36## Documentación de diseño (SDD)
37
38Toda la arquitectura está en [`docs/`](docs/). Empieza por
39[`docs/00-vision.md`](docs/00-vision.md) y [`docs/01-architecture.md`](docs/01-architecture.md).
40
41## Estructura
42
43```
44crates/
45  hammer-core   tipos compartidos: Recipe, Swm, hashing CAS, store
46  hammer-build  el laboratorio: sandbox + compilación + hidratación
47  hammer-cli    el binario `hammer` (build, hydrate, try, commit, apply, export…)
48  hammerd       daemon: bus de agente + diario de mutaciones
49docs/           SDDs y ADRs
50```
51
52## Stack
53
54| Capa | Decisión |
55|---|---|
56| Base de validación | Alpine (musl + FHS mutable) |
57| Tooling / daemons | Rust (estático-musl) |
58| Compilador del lab | `zig cc` por defecto, pluggable por receta |
59| Sandbox de build | bubblewrap (namespaces) |
60| Direccionamiento | BLAKE3 content-addressed store |
61| Despliegue | Hidratación por hardlinks + patchelf |
62
63## Filosofía
64
65> La automatización es mi empleada en el sótano, pero en el piso de arriba mando yo.
66
67Eficiencia matemática en la manufactura, libertad biológica en la ejecución.