# Fase 21 — Atlas :: el explorador del grafo

> *El paralelo a un explorador de archivos en un sistema que no tiene
> archivos. renaser nunca tuvo carpetas: tiene un grafo de objetos
> direccionado por contenido (BLAKE3 + postcard sobre virtio-blk). Lo
> que ha estado bajo el agua desde la Fase 7 sale a la superficie con
> una piel navegable.*

---

## 1. La idea

`atlas` es la primera app que **lee** del grafo persistente desde el
userspace. Hasta hoy, solo el kernel toca el grafo: las apps ven su
ranura `EntradaApp.estado` y nada más. Esta fase invierte la asimetría:
las apps reciben tres capacidades de inspección read-only y `atlas` las
ejerce mostrando, en pantalla, la topología del grafo —el manifiesto,
los bytecodes, los estados, las raíces— como un atlas de regiones
conectadas por aristas.

La elección de la metáfora es deliberada. Un explorador de archivos
representa un sistema jerárquico (Unix) o un sistema con etiquetas y
versiones (Plan 9, Git). El grafo de renaser no es ninguno de los dos:
es un DAG inmutable, direccionado por contenido, con dos anclas
(`raiz`, `manifiesto`). El paralelo natural es un **atlas**: un mapa de
territorios donde cada nodo es una localidad, cada arista una frontera,
y la identidad de la localidad es su contenido —no un nombre—.

## 2. Tres capas, tres responsabilidades

### Capa 1 — capacidades de host `sys_grafo_*` (kernel/src/wasm/env.rs)

Cuatro caps nuevas. Todas read-only. Validan rango contra la memoria
lineal del módulo. Idéntico patrón a los `sys_net_*` de la Fase 19.

| Capacidad | Firma | Salida | Errores |
|---|---|---|---|
| `sys_grafo_manifiesto` | `(hash_out: u32) -> i32` | escribe 32 B del hash del manifiesto | `-1` sin ancla |
| `sys_grafo_raiz` | `(hash_out: u32) -> i32` | escribe 32 B del hash de la raíz | `-1` sin ancla |
| `sys_grafo_recuperar` | `(hash_in, datos_out, datos_cap, info_out) -> i32` | escribe `datos` truncados a `datos_cap` + struct `{datos_total_len, n_hijos, datos_escritos}` (12 B) en `info_out` | `-1` objeto no encontrado, `-2` rango fuera de memoria |
| `sys_grafo_hijo` | `(hash_in, indice, hash_out) -> i32` | escribe el hash del hijo `indice` | `-1` objeto ausente, `-2` índice fuera de rango |

Punto delicado: `sys_grafo_recuperar` **rehashea** el payload servido
para que el módulo nunca reciba bytes corruptos atribuidos a un hash
que no les corresponde. El grafo ya hace esto en `almacen::recuperar`;
heredamos esa garantía sin código nuevo.

### Capa 2 — la app `atlas` (apps/atlas/, wasm32)

Lienzo natural ~520×400, en la misma paleta índigo del compositor.

Estado mínimo:

```rust
struct Vista {
    foco: Hash,                      // nodo central
    historial: Vec<Hash>,            // breadcrumbs para volver
    cache: BTreeMap<Hash, NodoInfo>, // LRU pequeña (16 entradas)
    seleccionado: usize,             // qué hijo está marcado
}

struct NodoInfo {
    hash: Hash,
    datos_preview: [u8; 96],   // primeros bytes del payload
    datos_len_total: u32,      // tamaño completo del payload
    n_hijos: u32,              // cuántas aristas salen
    hijos: Vec<Hash>,          // resueltos perezosamente
}
```

Flujo:

1. Al `init`, llamar `sys_grafo_manifiesto` y empezar centrados ahí.
2. En cada `tick`, recoger teclas del compositor (ya las recibe la
   ventana enfocada vía la Fase 8c) y mover el cursor / cambiar de
   nodo en consecuencia.
3. Cualquier nodo nuevo se carga perezosamente con `sys_grafo_recuperar`
   y se cachea.

Navegación:

- ← / → mueven el cursor entre hijos del foco actual.
- Enter desciende: el hijo seleccionado pasa a ser el nuevo foco; el
  anterior va al historial.
- Backspace asciende: vuelve al último foco del historial.
- Esc reinicia al manifiesto.
- `r` re-ancla al `raiz` si la hay (toggle manifiesto / raíz).

### Capa 3 — la pintura: «la elegancia de la graficación»

La representación es **radial**, no lista. Es lo que distingue a
`atlas` de un explorador de archivos clásico:

```
                       ┌──────────────┐
                       │   PADRE      │
                       │  hash...     │
                       └──────┬───────┘
                              │
                       ┌──────┴───────┐
                       │              │
                       │    FOCO      │      ← centrado, grande
                       │  hash + meta │
                       └──┬──┬──┬─────┘
                          │  │  │
                  ┌───────┘  │  └───────┐
              ┌───┴──┐  ┌────┴───┐  ┌──┴──┐
              │ HIJO │  │  HIJO  │  │HIJO │
              │ ●    │  │   ●    │  │  ●  │   ← círculo radial
              └──────┘  └────────┘  └─────┘
```

- **Foco**: en el centro del lienzo, recuadro grande con su hash
  abreviado (primeros 8 hex), tamaño del payload, número de hijos.
  Color del recuadro derivado de los primeros 3 bytes del hash —cada
  objeto tiene su propia firma cromática estable—.
- **Hijos**: hasta 8 a la vez, dispuestos en círculo alrededor del foco.
  Si hay más, una pequeña indicación `+N` en la circunferencia, con
  teclas `[` / `]` para rotar la página de hijos visible.
- **Padre**: si hay historial, se dibuja como una pista flotante arriba,
  conectada al foco por una arista vertical.
- **Aristas**: trazadas con Bresenham, color tenue (`TINTA_TENUE`); la
  arista al hijo seleccionado se realza en `ETIQUETA`.
- **Cartela inferior**: la huella completa (32 hex), el tamaño total y
  la previsualización del payload —si los primeros bytes pasan el test
  ASCII imprimible, se muestra como texto; si no, como hex—.

Cada **previsualización** es lo que cierra la metáfora: un objeto que
contiene texto (la bitácora persistida, el manifiesto serializado) se
delata por su payload legible. Uno binario muestra su silueta en hex.

## 3. Subfases y criterios de cierre

**21a — capacidades de host** *(≈ 1 sesión corta)*

- [ ] Añadir las 4 caps al `wasm/env.rs` con sus rangos validados.
- [ ] Almacenar tabletas de tests: pedir el manifiesto y un nodo
      conocido desde una app de prueba.
- [ ] Cerrar cuando una mini-app de prueba imprime el hash del
      manifiesto en pantalla.

**21b — la app `atlas` con navegación radial** *(≈ 1 sesión larga)*

- [ ] Crate `apps/atlas/` con `font8x8`, `init` carga el manifiesto.
- [ ] Pintar el foco + sus hijos en círculo, sin selección.
- [ ] Teclado: cursor entre hijos, Enter descender, Backspace volver.
- [ ] Cartela con hash + tamaño + previsualización.
- [ ] Añadir a `GENESIS` (10ª app); `CELDA_TASKBAR_ANCHO` 116→106 px
      para que las diez pestañas caben holgadas en 1280 px.
- [ ] Cerrar cuando se verifica en QEMU: arranca apuntando al
      manifiesto, se navega a un hijo (un bytecode WASM), se ve el
      tamaño y los primeros bytes; se vuelve con Backspace.

**21c — el paseo guiado** *(opcional, si queda margen)*

- [ ] Tecla `r` alterna entre las dos anclas (manifiesto / raíz).
- [ ] Indicador de la naturaleza del nodo: si su `datos` deserializa
      como `Manifiesto`, mostrar «manifiesto»; si es un `.wasm`
      (magic bytes `\0asm`), mostrar «bytecode»; si es texto ASCII,
      mostrar «texto»; el resto «opaco».
- [ ] Pruebas integradas con la sustitución del disco (eliminar
      `target/disk.img` y re-sembrar): `atlas` muestra el árbol de
      semilla; tras editar en `bitacora`, `atlas` revela el nuevo
      `estado` colgando del manifiesto.

## 4. Qué eficiencia aprovecha

- **Direccionamiento por contenido**: cuando dos apps comparten
  bytecode (ej. dos `hola` clonadas), `atlas` lo muestra como UN nodo
  con dos aristas entrantes —la dedup ya inherente al grafo se vuelve
  visible—.
- **`almacen::recuperar` es O(1)**: el índice `BTreeMap<Hash, sector>`
  ya está construido; cada navegación es una sola consulta + una
  lectura de disco asíncrona (Fase 6.2).
- **Lazy loading + cache**: solo cargamos lo que está a un salto del
  foco actual. El cache LRU de 16 entradas cubre la cuenca de
  navegación humana.
- **El grafo es pequeño hoy** (~25 objetos). Una visualización completa
  brute-force ya cabría —no necesitamos algoritmos sofisticados de
  layout—.

## 5. Qué mejora el sistema (no solo añade)

1. **Primer caso de uso del grafo desde el userspace**. Asentamos el
   patrón que toda app futura que quiera leer datos compartidos seguirá.
2. **Surface lo invisible**. El grafo era una propiedad estructural
   indirecta; ahora es un objeto observable. Los bugs del almacén (si
   los hubiera) se delatan visualmente.
3. **Validación de integridad por uso**. Cada navegación rehashea el
   payload servido. Si un sector se corrompe en virtio-blk, `atlas` lo
   descubrirá antes que ningún test.
4. **Camino natural a Fase 22 (escritura)**. Una vez que las apps leen,
   la siguiente capacidad lógica es escribir: `sys_grafo_almacenar`,
   `sys_grafo_anclar_raiz`. `atlas` se convertirá entonces en un
   editor del grafo, no solo un explorador.
5. **Sinergia con Akasha** (Fase 20). El `AnunciarRaiz` que emite el
   kernel anuncia el hash del manifiesto. Quien reciba el faro y use
   `atlas` podrá descubrir qué tiene un par —el explorador y el
   protocolo distribuido se complementan—.

## 6. Riesgos y mitigaciones

- **WASM lento bajo wasmi**: el descubrimiento de la Fase 20 (los apps
  degradan la cadencia del reactor a ~600 ms/iter cuando hay muchos)
  aplica aquí. `atlas` debe pintar UNA vez por interacción, no por
  fotograma; usar el lienzo cacheado entre teclas.
- **Lienzo grande**: 520×400 a 4 B/píxel = 832 KiB. Cabe en el techo
  de 4 MiB de cada app. Sin holgura para optimizar, pero suficiente.
- **Profundidad del grafo**: si el grafo creciera mucho, la navegación
  con cursor entre 8 hijos visibles a la vez se quedaría corta. El
  toggle `[` / `]` de rotación basta para hoy; un Fase 22 puede
  introducir búsqueda por prefijo de hash.

## 7. Cosecha visual prevista

Al cerrar la Fase 21, una captura headless mostrará algo así (el
contenido exacto cambia con el grafo):

```
┌── atlas :: el explorador del grafo ──────────────────────┐
│                                                          │
│                  ┌─────────────┐                         │
│                  │   raiz·??   │ (si la hay, en cima)    │
│                  └──────┬──────┘                         │
│                         │                                │
│                  ┌──────┴──────┐                         │
│                  │ MANIFIESTO  │  ← foco                 │
│                  │ 2f3deadf... │                         │
│                  │  9 hijos    │                         │
│                  │ 510 bytes   │                         │
│                  └─┬─┬─┬─┬─┬───┘                         │
│         ┌─────────┘ │ │ │ │ └─────────┐                  │
│      ┌──┴──┐    ┌───┴─┴─┴───┐    ┌────┴──┐               │
│      │ ●   │    │     ●      │   │   ●   │               │
│      │bita-│    │  pregon.. │   │ tonada│  ...           │
│      │cora │    │             │   │       │               │
│      └─────┘    └─────────────┘   └───────┘               │
│                                                          │
│ ─── 2f3deadfcc7dae25c4d... (32 hex) ─ 510 B ─ texto: ─── │
│ {"version":1,"apps":[{"nombre":"bitacora","bytecode":..  │
└──────────────────────────────────────────────────────────┘
```

El sistema, que hasta hoy era un grafo silencioso, gana un mapa.

