1# SDD 01 — Arquitectura general
2
3## 1. El modelo de dos mundos
4
5```
6                          EL SÓTANO (laboratorio)                 EL PISO DE ARRIBA (userland)
7                          determinista · hermético                mutable · clásico · FHS real
8   ┌──────────────────────────────────────────────┐   ┌─────────────────────────────────────────┐
9   │                                                │   │                                           │
10   │  [ Upstreams: git, commits FIJADOS ]           │   │   /bin  /sbin  /lib  /etc   (FHS clásico) │
11   │            │                                   │   │      ▲                                    │
12   │            ▼                                   │   │      │  hardlinks normalizados            │
13   │  ┌───────────────────────┐                     │   │      │                                    │
14   │  │  takana-build (lab)    │                     │   │  ┌───┴──────────────┐                     │
15   │  │  bubblewrap + zig cc   │   compila musl      │   │  │   HIDRATACIÓN     │  patchelf / copy    │
16   │  │  recetas + grafo deps  │   estático          │   │  └───┬──────────────┘                     │
17   │  └──────────┬────────────┘                     │   │      │                                    │
18   │             ▼                                   │   │      │                                    │
19   │  ┌───────────────────────┐                     │   │  ┌───┴───────────────┐                    │
20   │  │  CAS store (BLAKE3)    │ ────────────────────┼───┼─▶│  overlay try/commit │ red de seguridad │
21   │  │  /store/<hash>-<name> │                     │   │  └───┬───────────────┘                    │
22   │  └───────────────────────┘                     │   │      │                                    │
23   │                                                │   │  ┌───┴───────────────┐                    │
24   └──────────────────────────────────────────────┘   │  │  diario fanotify    │  delta vs base    │
25                                                        │  └───┬───────────────┘                    │
26            ┌───────────────────────────────────────────────┐ │                                    │
27            │  BUS DE AGENTE  /run/agent.sock (JSON-líneas)   │◀┘   /run/init.control (FIFO humano)  │
28            │  COMPILE · INJECT · QUERY · eventos             │                                       │
29            └───────────────────────────┬────────────────────┘                                       │
30                                         │                    └─────────────────────────────────────┘
31                                         ▼
32                                  [ IA programadora ]  intención NL → .swm → overlay → test → aprobar
33```
34
35**Regla de oro:** los dos mundos nunca se mezclan. El lab jamás escribe directamente en el
36FHS real; siempre pasa por el store y luego por hidratación. El userland jamás compila contra
37el host; siempre delega al lab.
38
39## 2. Componentes y su responsabilidad
40
41| Componente | Crate | Responsabilidad única |
42|---|---|---|
43| **Laboratorio** | `takana-build` | Compilar una receta de forma hermética → artefacto en el store |
44| **Store CAS** | `takana-core` | Guardar/recuperar artefactos por hash BLAKE3; garbage collection |
45| **Hidratación** | `takana-build` | Proyectar artefactos del store al FHS real (hardlink + patchelf) |
46| **Overlay** | `takana-cli` | Montar/fusionar/descartar capa de experimentación en caliente |
47| **Diario** | `hammerd` | Vigilar mutaciones (fanotify), log append-only, exportar `.swm` |
48| **Bus de agente** | `hammerd` | Socket de control para IA/scripts; eventos del sistema |
49| **CLI** | `takana-cli` | El binario `takana` que orquesta todo lo anterior |
50| **Tipos compartidos** | `takana-core` | `Recipe`, `Swm`, `Hash`, `Store`, formatos serializables |
51
52## 3. Flujo de datos canónico (de la intención al sistema vivo)
53
541. **Intención** — el humano (o la IA) expresa un cambio: *"que grep ignore binarios por
55   defecto y use regex Perl"*.
562. **Receta** — se traduce a una `Recipe`: repo + commit fijado + patch + flags + compilador.
573. **Build** — `takana-build` levanta el sandbox, compila con `zig cc`, produce un binario
58   musl estático, lo deposita en el store bajo `BLAKE3(...)`.
594. **Overlay** — el artefacto se hidrata, pero **en una capa overlay temporal**, no en el
60   sistema real. El humano/IA prueba en caliente.
615. **Validación** — corre el test harness; los eventos van por el bus (`BUILD_READY`,
62   `CRASHED`). Si falla, se descarta el overlay; el sistema base intacto.
636. **Promoción** — si pasa, se fusiona al FHS real. El diario registra la mutación.
647. **Compartir** — `takana export` empaqueta el delta como `.swm`: base-hash + patch + config.
65   Otro usuario lo `apply`-ea: su IA reproduce y verifica localmente; nunca ejecuta tu binario.
66
67## 4. Estado en disco (layout)
68
69```
70/store/                      el content-addressed store (inmutable, append-only)
71  <blake3>-<name>/           un artefacto: árbol de archivos resultante de un build
72/var/lib/hammer/
73  recipes/                   recetas conocidas (caché de definiciones)
74  pins.toml                  lockfile: nombre → commit fijado del upstream
75  journal/                   diario de mutaciones append-only
76  overlays/                  upperdirs de overlays activos
77/run/
78  init.control              FIFO de control humano (texto crudo)
79  agent.sock                socket de control de agente (JSON-líneas, SO_PEERCRED)
80  hammerd.pid
81```
82
83> Nota: en la fase Alpine, `/store` y `/var/lib/hammer` viven dentro del rootfs de Alpine.
84> En la distro propia se decidirá su partición/montaje. Ver [SDD 10](10-roadmap.md).
85
86## 5. Límites del sistema (qué corre dónde)
87
88- **`takana-build`** corre privilegiado lo justo para crear namespaces (vía `bubblewrap`,
89  que usa user-namespaces sin root real cuando es posible).
90- **`hammerd`** corre como servicio bajo el init; expone el bus y vigila el diario.
91- **`takana` (CLI)** corre como el usuario; es el punto de entrada de todo flujo manual.
92- **La IA** es un cliente del bus como cualquier otro proceso — sin privilegios especiales
93  más allá de los que el humano le conceda explícitamente (ver [SDD 08](08-ai-integration.md)).
94
95## 6. Decisiones transversales
96
97- Reproducibilidad ⇒ commits fijados, no HEAD ([ADR 0006](adr/0006-pinned-commits.md)).
98- No reescribir el motor de build ([ADR 0004](adr/0004-no-custom-nix.md)).
99- Validar el concepto sobre Alpine primero ([ADR 0002](adr/0002-alpine-first.md)).