Sergio
97ceb72411
645 líneas. Los ADR entran porque en este repo SON documentos vivos, no registros inmutables: el 0013 tiene 5 commits, el 0009 dos. Eso se comprobó antes de decidir, no se asumió por convención general. EXCLUIDOS por ser REGISTRO o generado: docs/evidencia/ (6), el HANDOFF de la noche de KDE (1) y docs/state/ (24, se regenera solo). Reescribir un comando dentro de una evidencia la falsifica. Y el ADR 0016 se excluye de todo barrido, con un aviso adentro para el próximo que barra: habla SOBRE el renombre, así que necesita seguir diciendo 'hammer'. El barrido se lo llevó puesto y lo dejó titulado 'Renombre del sistema: takana → takana'; revertido. Congelados, verificados uno por uno con controles: /opt/hammer, /var/lib/hammer, /usr/bin/hammer, /mnt/vvv/hammer, la URL de gitea, hammer-farm.service, hammer-live-install.sh, BRIEFING-hammer.md, hammerd, hammer-recover y HAMMER_LIVE.
100 lines
7.7 KiB
Markdown
100 lines
7.7 KiB
Markdown
# 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 │
|
|
│ ┌───────────────────────┐ │ │ │ │
|
|
│ │ takana-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** | `takana-build` | Compilar una receta de forma hermética → artefacto en el store |
|
|
| **Store CAS** | `takana-core` | Guardar/recuperar artefactos por hash BLAKE3; garbage collection |
|
|
| **Hidratación** | `takana-build` | Proyectar artefactos del store al FHS real (hardlink + patchelf) |
|
|
| **Overlay** | `takana-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** | `takana-cli` | El binario `takana` que orquesta todo lo anterior |
|
|
| **Tipos compartidos** | `takana-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** — `takana-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** — `takana 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)
|
|
|
|
- **`takana-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.
|
|
- **`takana` (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)).
|