sergio/hammer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Scaffold inicial: workspace Rust + SDDs completos

Browse Source 
Arranque del proyecto hammer (distro AI-nativa: laboratorio funcional en el
sótano, terminal mutable clásica arriba, integración de IA programadora).

- Workspace Rust (compila, tests verdes): hammer-core, hammer-build,
  hammer-cli (bin `hammer`), hammerd.
- SDDs 00-10 + 6 ADRs en docs/ con toda la arquitectura.
- Esqueletos navegables mapeados a las fases del roadmap; Fase 0/1 listas
  para implementar el sandbox real.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
sergio
2026-06-06 19:06:04 +00:00
co-authored by Claude Opus 4.8
commit 8bf1623044
37 changed files with 2746 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/01-architecture.md
+99
View File
@@ -0,0 +1,99 @@
# SDD 01 — Arquitectura general
## 1. El modelo de dos mundos
```
EL SÓTANO (laboratorio) EL PISO DE ARRIBA (userland)
determinista · hermético mutable · clásico · FHS real
┌──────────────────────────────────────────────┐ ┌─────────────────────────────────────────┐
│ │ │ │
│ [ Upstreams: git, commits FIJADOS ] │ │ /bin /sbin /lib /etc (FHS clásico) │
│ │ │ │ ▲ │
│ ▼ │ │ │ hardlinks normalizados │
│ ┌───────────────────────┐ │ │ │ │
│ │ hammer-build (lab) │ │ │ ┌───┴──────────────┐ │
│ │ bubblewrap + zig cc │ compila musl │ │ │ HIDRATACIÓN │ patchelf / copy │
│ │ recetas + grafo deps │ estático │ │ └───┬──────────────┘ │
│ └──────────┬────────────┘ │ │ │ │
│ ▼ │ │ │ │
│ ┌───────────────────────┐ │ │ ┌───┴───────────────┐ │
│ │ CAS store (BLAKE3) │ ────────────────────┼───┼─▶│ overlay try/commit │ red de seguridad │
│ │ /store/<hash>-<name> │ │ │ └───┬───────────────┘ │
│ └───────────────────────┘ │ │ │ │
│ │ │ ┌───┴───────────────┐ │
└──────────────────────────────────────────────┘ │ │ diario fanotify │ delta vs base │
│ └───┬───────────────┘ │
┌───────────────────────────────────────────────┐ │ │
│ BUS DE AGENTE /run/agent.sock (JSON-líneas) │◀┘ /run/init.control (FIFO humano) │
│ COMPILE · INJECT · QUERY · eventos │ │
└───────────────────────────┬────────────────────┘ │
│ └─────────────────────────────────────┘
▼
[ IA programadora ] intención NL → .swm → overlay → test → aprobar
```
**Regla de oro:** los dos mundos nunca se mezclan. El lab jamás escribe directamente en el
FHS real; siempre pasa por el store y luego por hidratación. El userland jamás compila contra
el host; siempre delega al lab.
## 2. Componentes y su responsabilidad
| Componente | Crate | Responsabilidad única |
|---|---|---|
| **Laboratorio** | `hammer-build` | Compilar una receta de forma hermética → artefacto en el store |
| **Store CAS** | `hammer-core` | Guardar/recuperar artefactos por hash BLAKE3; garbage collection |
| **Hidratación** | `hammer-build` | Proyectar artefactos del store al FHS real (hardlink + patchelf) |
| **Overlay** | `hammer-cli` | Montar/fusionar/descartar capa de experimentación en caliente |
| **Diario** | `hammerd` | Vigilar mutaciones (fanotify), log append-only, exportar `.swm` |
| **Bus de agente** | `hammerd` | Socket de control para IA/scripts; eventos del sistema |
| **CLI** | `hammer-cli` | El binario `hammer` que orquesta todo lo anterior |
| **Tipos compartidos** | `hammer-core` | `Recipe`, `Swm`, `Hash`, `Store`, formatos serializables |
## 3. Flujo de datos canónico (de la intención al sistema vivo)
1. **Intención** — el humano (o la IA) expresa un cambio: *"que grep ignore binarios por
defecto y use regex Perl"*.
2. **Receta** — se traduce a una `Recipe`: repo + commit fijado + patch + flags + compilador.
3. **Build** — `hammer-build` levanta el sandbox, compila con `zig cc`, produce un binario
musl estático, lo deposita en el store bajo `BLAKE3(...)`.
4. **Overlay** — el artefacto se hidrata, pero **en una capa overlay temporal**, no en el
sistema real. El humano/IA prueba en caliente.
5. **Validación** — corre el test harness; los eventos van por el bus (`BUILD_READY`,
`CRASHED`). Si falla, se descarta el overlay; el sistema base intacto.
6. **Promoción** — si pasa, se fusiona al FHS real. El diario registra la mutación.
7. **Compartir** — `hammer export` empaqueta el delta como `.swm`: base-hash + patch + config.
Otro usuario lo `apply`-ea: su IA reproduce y verifica localmente; nunca ejecuta tu binario.
## 4. Estado en disco (layout)
```
/store/ el content-addressed store (inmutable, append-only)
<blake3>-<name>/ un artefacto: árbol de archivos resultante de un build
/var/lib/hammer/
recipes/ recetas conocidas (caché de definiciones)
pins.toml lockfile: nombre → commit fijado del upstream
journal/ diario de mutaciones append-only
overlays/ upperdirs de overlays activos
/run/
init.control FIFO de control humano (texto crudo)
agent.sock socket de control de agente (JSON-líneas, SO_PEERCRED)
hammerd.pid
```
> Nota: en la fase Alpine, `/store` y `/var/lib/hammer` viven dentro del rootfs de Alpine.
> En la distro propia se decidirá su partición/montaje. Ver [SDD 10](10-roadmap.md).
## 5. Límites del sistema (qué corre dónde)
- **`hammer-build`** corre privilegiado lo justo para crear namespaces (vía `bubblewrap`,
que usa user-namespaces sin root real cuando es posible).
- **`hammerd`** corre como servicio bajo el init; expone el bus y vigila el diario.
- **`hammer` (CLI)** corre como el usuario; es el punto de entrada de todo flujo manual.
- **La IA** es un cliente del bus como cualquier otro proceso — sin privilegios especiales
más allá de los que el humano le conceda explícitamente (ver [SDD 08](08-ai-integration.md)).
## 6. Decisiones transversales
- Reproducibilidad ⇒ commits fijados, no HEAD ([ADR 0006](adr/0006-pinned-commits.md)).
- No reescribir el motor de build ([ADR 0004](adr/0004-no-custom-nix.md)).
- Validar el concepto sobre Alpine primero ([ADR 0002](adr/0002-alpine-first.md)).