# hammer

> Una distribución Linux construida con un **laboratorio funcional y hermético** en el
> sótano, y una **terminal mutable, clásica y anárquica** en el piso de arriba — diseñada
> desde el suelo para que una **IA programadora** entienda, modifique y comparta el sistema.

`hammer` no es otro gestor de paquetes inmutable. Es una arquitectura de dos mundos:

- **El laboratorio** compila desde fuentes upstream (commits fijados), de forma
  determinista y aislada (`bubblewrap` + `zig cc` + musl estático), y direcciona cada
  artefacto por su hash (BLAKE3) en un *content-addressed store*.
- **El userland** es un Linux clásico, mutable, con FHS de verdad (`/bin`, `/lib`, `/etc`).
  Los binarios se **hidratan** desde el store por *hardlinks*. Puedes pisar archivos en
  caliente, romper cosas con un `rm -rf`, y revertir cuando quieras.

Entre ambos mundos viven las tres piezas que hacen a `hammer` distinto:

1. **Overlay de experimentación** — prueba cambios sobre el sistema real con red de
   seguridad; `hammer try` / `commit` / `discard`.
2. **Diario de mutaciones** — un daemon `fanotify` registra todo lo que tú (o la IA)
   cambiáis a mano. Vives imperativamente; el sistema genera el delta contra la base
   limpia. **El diario es tu configuración — sin ser declarativa.**
3. **Manifiesto `.swm`** — compartes la *receta de la mutación* (parche de fuente + flags +
   ediciones de config), no el binario cocinado. El receptor **reproduce y verifica**; no
   confía en tu binario.

Encima de todo corre el **bus de agente** (`/run/agent.sock`): la IA habla un protocolo
pequeño y legible, dispara compilaciones, inyecta en el overlay, escucha fallos y reacciona.
Tú tienes la última palabra.

## Estado

Fase de arranque. Validamos la capa AI-nativa **sobre Alpine** (musl + FHS ya cocidos)
antes de bajar a distro propia. Ver [`docs/10-roadmap.md`](docs/10-roadmap.md).

## Documentación de diseño (SDD)

Toda la arquitectura está en [`docs/`](docs/). Empieza por
[`docs/00-vision.md`](docs/00-vision.md) y [`docs/01-architecture.md`](docs/01-architecture.md).

## Estructura

```
crates/
  hammer-core   tipos compartidos: Recipe, Swm, hashing CAS, store
  hammer-build  el laboratorio: sandbox + compilación + hidratación
  hammer-cli    el binario `hammer` (build, hydrate, try, commit, apply, export…)
  hammerd       daemon: bus de agente + diario de mutaciones
docs/           SDDs y ADRs
```

## Stack

| Capa | Decisión |
|---|---|
| Base de validación | Alpine (musl + FHS mutable) |
| Tooling / daemons | Rust (estático-musl) |
| Compilador del lab | `zig cc` por defecto, pluggable por receta |
| Sandbox de build | bubblewrap (namespaces) |
| Direccionamiento | BLAKE3 content-addressed store |
| Despliegue | Hidratación por hardlinks + patchelf |

## Filosofía

> La automatización es mi empleada en el sótano, pero en el piso de arriba mando yo.

Eficiencia matemática en la manufactura, libertad biológica en la ejecución.