1# SDD 04 — Overlay de experimentación
2
3El overlay es la red de seguridad que convierte la mutabilidad total en algo que también es
4seguro: la capacidad de **cometer errores sin perder el control imperativo**. Es donde la IA
5prueba sus cambios antes de tocar el sistema real, y donde tú experimentas a mano sin miedo.
6
7## 1. El mecanismo
8
9Usa `overlayfs` nativo del kernel, gestionado dinámicamente desde la terminal:
10
11```
12                 montaje overlay sobre /bin (y /etc, /lib…)
13  upperdir  →  /var/lib/hammer/overlays/<id>/upper   (tmpfs o dir oculto, MUTABLE)
14  lowerdir  →  el /bin real                          (read-only de facto bajo el overlay)
15  merged    →  /bin                                  (lo que ve el sistema)
16```
17
18Mientras el overlay está montado, el sistema y tú veis `/bin` como **el sistema real
19modificado en caliente**. Pero toda escritura cae en el `upperdir`; el `/bin` real (lowerdir)
20nunca se toca.
21
22## 2. El ciclo de vida
23
24```
25takana try            # monta un overlay sobre los directorios del sistema
26   ... experimentas / la IA inyecta binarios y edita configs ...
27   ... pruebas en caliente: ejecutas, rompes, observas ...
28takana commit         # fusiona upperdir → FHS real (rsync inteligente) y registra en el diario
29   — o —
30takana discard        # desmonta y borra el upperdir: el sistema vuelve al estado base, instantáneo
31```
32
33- **`try`** → estado base limpio + capa mutable encima. Riesgo cero.
34- **`discard`** → desmonta el overlay; el sistema vuelve a su base **instantáneamente**. No hay
35  que deshacer cambios uno por uno.
36- **`commit`** → fusiona la capa al FHS real y anota cada archivo tocado en el diario
37  ([SDD 05](05-journal.md)). A partir de aquí el cambio es permanente y rastreable.
38
39## 3. Por qué overlay y no contenedor
40
41Un contenedor (docker/chroot) te aísla de tus dispositivos y procesos reales — pierdes el
42acceso al sistema vivo. El overlay hace lo contrario: **modificas la "realidad" del sistema
43operativo** (mismos PIDs, mismos `/dev`, misma red) pero con una red de seguridad. Es la
44diferencia entre "probar en una maqueta" y "probar en la casa real con un seguro de vida".
45
46## 4. Composición con el resto del sistema
47
48- **La IA** (ver [SDD 08](08-ai-integration.md)) opera **siempre** dentro de un overlay: clona
49  el repo, compila en el lab, hidrata en el `upperdir`, edita configs en el `upper`. Tú validas
50  en caliente. La IA nunca escribe en el FHS real hasta que tú haces `commit`.
51- **Múltiples overlays** pueden coexistir (distintos `<id>`), p. ej. un experimento por
52  hipótesis. Cada uno es independiente.
53- **El diario** sólo registra en `commit` — el ruido del experimento no contamina la historia.
54
55## 5. Estados y reglas
56
57| Estado | Significado | Transiciones |
58|---|---|---|
59| `none` | sin overlay activo | `try` → `active` |
60| `active` | overlay montado, capa mutable encima | `commit` → `none` (+diario), `discard` → `none` |
61
62Reglas:
63- `commit`/`discard` sin overlay activo: no-op con aviso.
64- Un `try` anidado sobre un target ya cubierto crea un overlay nuevo **apilado**: el kernel
65  toma el merged view de la capa de abajo como `lowerdir` de la nueva. El orden de
66  apilamiento es total y determinista (`created_at`, desempatado por `id`, que ahora lleva un
67  `seq` por proceso para que ráfagas en el mismo segundo no colisionen). `commit`/`discard`
68  **exigen LIFO**: si una capa más joven aún sombrea alguno de tus targets, la operación
69  falla con `Error::Shadowed` listándolas — resuelve primero las de arriba. (La unicidad de
70  orden entre procesos concurrentes apilando sobre el mismo target en el mismo segundo no la
71  garantiza el `seq`; queda para el track posterior junto al init propio.)
72- Si el sistema se apaga con overlays activos, al arranque `hammerd` los reporta y deja que el
73  humano decida (no auto-commit, no auto-discard — eso sería declarativo).
74
75## 6. Interfaz
76
77```rust
78// takana-cli (con helpers de takana-core)
79pub fn overlay_try(targets: &[PathBuf]) -> Result<OverlayId>;
80pub fn overlay_commit(id: OverlayId, journal: &Journal) -> Result<CommitReport>;
81pub fn overlay_discard(id: OverlayId) -> Result<()>;
82pub fn overlay_status() -> Result<Vec<OverlayState>>;
83```
84
85CLI: `takana try` · `takana commit` · `takana discard` · `takana status`.