# SDD 18 — wawafs: el store como filesystem del sistema vivo (CAS + erofs + fs-verity)

> Origen: la pregunta "¿se podría hostear takana en un FS de grafos sobre discos en vivo,
> sacándole ventaja a ext4?" (2026-07-17). La respuesta corta: sí, y no hay que escribir un
> filesystem — la pila composefs (CAS + erofs + overlayfs + fs-verity, mainline) es exactamente
> esa idea, y el modelo de takana ya es casi isomorfo a ella. "wawafs" queda como apodo del
> frente; no es código de wawa (tawasuyu), es la misma filosofía content-addressed bajada al VFS.

**Estado:** diseño aceptado en conversación; sin implementar. **Fecha:** 2026-07-17.

## 1. Problema

Hoy la materialización del store al sistema vivo es **por copia u hardlink** (`takana hydrate
<hash> --into`, ADR 0005). Funciona y escala rebuild-free (el escritorio KDE son 137 artefactos
hidratados), pero en el **sistema desplegado** (live-disk, metal, generaciones de boot) paga
tres costos:

1. **Duplicación**: el store tiene los bytes y el rootfs hidratado tiene otra copia (o un
   hardlink que exige mismo-filesystem y se rompe silencioso al escribir encima).
2. **Integridad histórica, no vigente**: bit-repro es una propiedad del día del sellado; nada
   verifica el binario en cada lectura años después (bit-rot, disco vivo).
3. **Rollback O(bytes)**: cambiar de generación implica re-hidratar; dos generaciones = casi 2×
   disco si no comparten filesystem con el store.

## 2. La idea en una línea

**Bajar el checkout de userspace al kernel**: hoy `hydrate` es un checkout con copia (git-style:
store = DAG, hidratar = materializar el árbol); wawafs es el mismo checkout hecho *lazy* por el
VFS al montar, sin copiar un byte. ext4 queda abajo como capa de bloques tonta; la "evolución
sobre ext4" es la capa content-addressed encima — la arquitectura que takana ya tiene en
userspace, un nivel más abajo.

## 3. Las capas

```
proceso:  open("/usr/bin/kate") → fd normal; execve/mmap/musl sin cambios
   ▲ VFS (rutas FHS reales — no hay pueblo fantasma en la vista)
composefs mount (overlayfs data-only lowerdir + redirect)
   ▲ resuelve nombre → puntero por hash (sólo en el open frío; dcache después)
manifest erofs por clausura (~KB–MB): árbol de dirs + modos + punteros. CERO datos.
   ▲ direccionado por hash = un nodo del grafo de estados (ADR 0010)
CAS de objetos:  /store/objects/ab/cdef…  (archivos planos, 1 copia por contenido único)
   ▲ fs-verity opcional por objeto: el kernel verifica el Merkle tree EN CADA READ
ext4 — intacto, aburrido, sólo guarda archivos sueltos
```

Propiedades que caen solas:

- **Dedup de disco y de RAM**: contenido idéntico entre N clausuras = 1 copia en ext4 y 1
  entrada en page cache (la segunda app Qt arranca con las .so calientes).
- **Activar/rollback O(metadata)**: cambiar de generación = escribir unos KB de manifest y
  montar. Atómico.
- **Inmutabilidad estructural**: la vista es ro por construcción; "alguien escribió /usr" deja
  de ser un estado alcanzable.
- **bit-repro en runtime**: con fs-verity, el hash sellado lo hace cumplir el kernel en cada
  lectura de por vida (un bit podrido = EIO, no un binario silenciosamente distinto).

## 4. Identidad: dos granos, un mapa

- **Grano artefacto** (existente): ArtifactHash blake3 — identidad de recetas, sellado, grafo.
  No se toca.
- **Grano archivo** (nuevo, derivado): el CAS de objetos se indexa por el **digest fs-verity**
  (sha256, es lo que el kernel sabe verificar). Es una capa *derivada* del store: un comando
  (`takana fs manifest <ArtifactHash…>`) explota los árboles de N artefactos en objetos por
  archivo + genera el manifest erofs de la clausura. blake3 sigue siendo la identidad; el
  digest verity es el enforcement.

Misma jugada que ADR 0009 (paquete/módulo/función: granos distintos, identidades intactas,
un mapa entre ellos).

## 5. Relación con los ADRs vigentes

- **ADR 0005 (hardlinks) sigue vigente** para el lado dev/laptop: rutas reales *escribibles*,
  mutar con red de seguridad. wawafs no lo reemplaza: es el modo **despliegue** (ro). El corte
  cae donde el workload cambia de naturaleza: se escribe una vez al sellar, se lee mil veces al
  vivir. Los builds — escritura intensiva — siguen en ext4 plano; la indirección se paga sólo
  donde es barata. Bonus: cae la restricción "store y FHS en el mismo filesystem" y el agujero
  del hardlink roto en silencio.
- **ADR 0010 (arranque por grafo)**: encaje directo. Un nodo del `boot-graph.json` = un
  manifest erofs direccionado por hash; "activar un nodo" = montar su composefs como `/usr` de
  la generación. El menú de mirada navega el grafo; wawafs hace que elegir nodo cueste un mount.
- **ADR 0004 (no nix)**: esto tampoco es nix — no hay rutas crípticas en la vista (el proceso
  ve `/usr/bin/kate`, FHS real), no hay lenguaje de build nuevo, no hay daemon. Sólo mounts.
- **SDD 17 (cierres de frontera)**: refuerza los tres invariantes a la vez — bit-repro
  (verity en runtime), CAS (bajado al VFS), clausura (la vista montada ES la clausura, nada más).

## 6. Costos honestos

- **Open frío**: un lookup extra en el manifest erofs (µs; Android monta `/system` así en cada
  teléfono). Repetidos los absorbe el dentry cache; los `read()`/`mmap()` van directo al inode
  ext4 — el data path es nativo.
- **fs-verity**: ~0.8% de disco extra (árbol Merkle) + hash por página en el primer read (miss
  de page cache). Opt-in por objeto.
- **Complejidad**: dos recetas nuevas (`erofs-utils`, `composefs`) y un conversor
  store→objetos. El formato erofs/overlayfs es mainline y ajeno — no mantenemos un FS.

## 7. Precondiciones y gates (medidos, no supuestos)

1. **Kernel propio SIN soporte hoy**: `linux-generic.toml` ya trae `OVERLAY_FS` +
   `REDIRECT_DIR`/`METACOPY`/`XINO` (justo lo que composefs necesita del lado overlay), pero
   **falta `EROFS_FS` y `FS_VERITY`** (verificado 2026-07-17, líneas 45–51 de la receta).
   Agregar `-e EROFS_FS -e EROFS_FS_ZIP_ZSTD -e FS_VERITY` re-sella el kernel → **worker**
   (mismo patrón que el re-sellado LANDLOCK/IO_URING de frente-kikin).
2. **Recetas nuevas**: `erofs-utils` (mkfs.erofs) y `composefs` (mkcomposefs) — C, no existen
   en el catálogo → **worker** (el laptop no construye recetas C).
3. **Conversor**: `takana fs manifest` — explotar artefactos en objetos por archivo. El store
   actual (1608 artefactos, directorios por hash) no se toca; el CAS de objetos es derivado y
   regenerable.

## 8. Fases

- **F0 — spike en QEMU** (sin tocar nada de takana): rootfs Alpine con composefs-tools de
  paquete, `mkcomposefs` sobre UNA clausura hidratada (p.ej. la de KDE), montar, comparar
  `find | sort | b3sum` contra la hidratación por copia. Gate: árboles idénticos + medir
  open-frío y RAM compartida. Decide si el frente existe.
- **F1 — kernel + recetas**: configs EROFS/FS_VERITY en `linux-generic.toml` (re-sellar en
  worker) + recetas `erofs-utils`/`composefs`. Gate: el kernel propio montando el spike de F0.
- **F2 — `takana fs manifest` + generaciones**: manifest erofs por clausura, generación de boot
  = manifest por hash, arje monta `/usr` de la generación elegida (contrato ADR 0010). Gate:
  bootear en QEMU una generación montada, rollback = elegir otro nodo en el menú.
- **F3 — sellado verity + live media**: fs-verity en el CAS de objetos; evaluar erofs como
  reemplazo de squashfs en el USB live (es el patrón vigente en Fedora/Android). Gate: bit
  flipeado a mano en un objeto ⇒ EIO en lectura, no ejecución.

## 9. Layouts de instalación (el corte ro/rw es de MOUNTS, no de particiones)

La parte ro no ocupa partición: es una vista sintética montada desde el CAS. Las particiones
guardan siempre lo mutable + el store. Dos instalaciones tipo:

**A — un solo ext4 en `/`** (particionado idéntico a una instalación normal: ESP + 1 ext4):

```
/                ext4 rw     /etc /var /home /root /run /store …
├─ /store/objects/…          CAS plano en este mismo ext4
├─ /store/manifests/<hash>   manifests erofs por generación (~KB)
└─ /usr          composefs ro — mount sintético de la generación activa
```

arje monta `/`, lee el nodo elegido del boot-graph, monta su manifest como `/usr`. Fin.

**B — `/home` y `/var` en particiones propias**:

```
/       ext4 rw (chica: /etc, /root, /store)
/usr    composefs ro
/var    ext4 rw propia      ← estado puro: ni se entera de wawafs
/home   ext4 rw propia      ← ídem
```

`/home`/`/var` son ortogonales al esquema. El caso B además *mejora*: la restricción de
ADR 0005 (store y FHS mismo-filesystem) desaparece — el redirect de composefs cruza mounts,
el store podría incluso tener partición propia.

Reglas del patrón:

- **ro**: `/usr` = el OS entero (requiere usr-merge para que un mount lo cubra todo).
- **rw**: `/etc` (se hidrata al activar la generación), `/var`, `/home`, `/root`, `/run`,
  `/tmp` y el propio `/store`.
- **Actualizar** = escribir objetos+manifest nuevos en `/store` (rw) y cambiar el mount;
  la generación corriendo nunca se toca.
- **Parchear `/usr` a mano** = modo dev (ADR 0005) o un overlay rw de emergencia explícito
  encima del mount; nunca un estado alcanzable por accidente.

## 10. No-metas

- **No** escribir un filesystem de kernel (años de fsck y corrupción ajena: landmine).
- **No** reemplazar `hydrate`/hardlinks en el laptop de desarrollo (ADR 0005 queda).
- **No** tocar el build lab ni el sellado: el CAS de objetos es una proyección derivada del
  store, nunca la fuente de verdad.