docs(renaser): plan de la Fase 21 — Atlas, el explorador del grafo
Plan trazado para mañana. Tres capas:
1. Cuatro capacidades de host read-only (sys_grafo_manifiesto,
sys_grafo_raiz, sys_grafo_recuperar, sys_grafo_hijo) que abren
el grafo de objetos al userspace. Mismo patron de validacion
de memoria que sys_net_*.
2. La app 'atlas': lienzo ~520x400, lee el grafo perezosamente con
cache LRU de 16 entradas, navega con flechas / Enter / Backspace
desde el manifiesto hacia los hijos.
3. Representacion radial: foco central con su firma cromatica
(3 primeros bytes del hash), hijos en circulo, padre en cima
si hay historial, cartela inferior con hash completo + tamaño
+ previsualizacion (texto si pasa el test ASCII, hex si no).
Subfases 21a (caps), 21b (app navegable), 21c (paseo guiado).
Sinergias y mejoras del sistema documentadas: dedup visual del
grafo direccionado por contenido, integridad por uso (cada
navegacion rehashea), validacion del almacen, camino natural a la
escritura (Fase 22), encaje con el faro Akasha de la Fase 20
(quien recibe AnunciarRaiz puede explorar la raiz del par).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
sergio
@@ -0,0 +1,245 @@
|
||||
# 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.
|
||||
|
||||
Reference in New Issue
Block a user