brahman/renaser/FASE_21_ATLAS.md

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:

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.