brahman/renaser/CLAUDE.md

renaser — guía operativa

renaser es un kernel asíncrono de Espacio de Direccionamiento Único (SASOS) en Rust #![no_std], bare-metal x86_64. Rompe con POSIX: interfaz visual nativa desde el arranque, aislamiento por software (no por MMU), el texto como caso particular del dibujo.

Documentos hermanos: ARCHITECTURE.md (arquitectura), ROADMAP.md (fases y plan), CHANGELOG.md (registro técnico de cambios), DIARIO.md (crónica en lenguaje llano), README.md (presentación).

Construir y ejecutar

Desde la raíz del repositorio:

Comando	Efecto
cargo run	compila el kernel, forja la imagen UEFI y abre QEMU
cargo build	compila el kernel + la imagen, sin lanzar QEMU
cargo kernel	alias: compila solo el kernel para x86_64-unknown-none

Verificación headless (sin ventana): añadir -- -display none -monitor unix:/tmp/q.sock,server,nowait y capturar con screendump por el socket del monitor.

Reconstruir una app WASM del userspace tras tocarla. Los .wasm viven en kernel/assets/ —de ahí los lee boot al sembrar la imagen (Fase 7b)—; el modulo hello_wasm se copia como app.wasm, el resto conserva su nombre:

cd apps/<app>            # hello_wasm, discola, glotona, cronista, memoriosa, pulso, tonada, bitacora
cargo build --target wasm32-unknown-unknown --release
cp target/wasm32-unknown-unknown/release/<app>.wasm ../../kernel/assets/<app>.wasm
# (hello_wasm es la excepcion: su destino es kernel/assets/app.wasm)

Estructura del espacio de trabajo

• boot/ — orquestador de anfitrión: construye la imagen de disco UEFI con la crate bootloader 0.11 y lanza QEMU. Es el único miembro del workspace.
• kernel/ — el kernel bare-metal. Está excluido del workspace y se compila solo como dependencia de artefacto de boot (target x86_64-unknown-none). NUNCA debe ser miembro del workspace ni compilarse para el anfitrión: lo haría fallar por un _start duplicado.
• apps/ — aplicaciones del userspace, módulos .wasm (target wasm32-unknown-unknown). Workspaces propios, excluidos.

Módulos del kernel (kernel/src/): main, grafico, consola, compositor, baliza, sync, gdt, interrupts, pic, drivers/, almacen, manifiesto, memory/, async_system/, texto, wasm/. El detalle de cada uno está en ARCHITECTURE.md.

Toolchain

Nightly, fijado en rust-toolchain.toml. Targets x86_64-unknown-none y wasm32-unknown-unknown. Componentes rust-src y llvm-tools (los exige el build script de la crate bootloader). Entorno verificado: Artix Linux, QEMU 11, OVMF en /usr/share/edk2/x64/OVMF.4m.fd (sin módulo KVM → TCG).

Convenciones

• Idioma: comentarios E identificadores en español.
• unsafe: confinado en células mínimas, envuelto de inmediato en una abstracción segura. #![deny(unsafe_op_in_unsafe_fn)]. Cada bloque unsafe lleva un comentario SEGURIDAD: que justifica su corrección.
• Framebuffer / MMIO: siempre core::ptr::write_volatile; jamás asignación indexada directa (el optimizador la elidiría).
• no_std estricto: solo core::* y alloc::* (heap vivo desde la Fase 3). Prohibido cualquier ruta de std::*.
• Alineación: 16 bytes para estructuras genéricas; 4096 bytes (página) para buffers de memoria y regiones de asignador.
• Código densamente comentado; se cuida la coherencia de estilo entre módulos.

Estado

Fases 1 a 5, 6.0, 6.1, 6.2, la Fase 7 COMPLETA —el userspace nace del grafo de objetos—, la Fase 8 COMPLETA —el compositor teselante e interactivo: teselado con mirada-layout (8a), ciclado de layout (8b), foco y enrutamiento selectivo del teclado (8c), promoción y reordenación de ventanas (8d)—, la Fase 9 COMPLETA —orden-Z y ventanas flotantes: composición con solapamiento (Alt+F)— la Fase 10 COMPLETA —alta y baja de aplicaciones en vivo (Alt+N / Alt+Q)—, la Fase 11 COMPLETA —el reloj del sistema como capacidad de host (sys_tiempo_mono) + la app pulso—, la Fase 12 COMPLETA —la bocina del PC como capacidad de host (sys_tono) + la app tonada—, la Fase 13 COMPLETA —ratón PS/2, puntero, clic-para-enfocar y arrastre de ventanas flotantes—, infraestructura memory::mmio (mapeador propio de regiones MMIO en la tabla L4), la Fase 14 COMPLETA —nombres en cada ventana y barra de tareas con clic-para-enfocar—, la Fase 15 COMPLETA —la voz del sistema: acorde al arrancar, repique al lanzar o cerrar, bajo al desalojar, con prioridad sobre sys_tono— la Fase 16 COMPLETA —la barra viva: botón «+» lanzador a la izquierda y reloj mm:ss a la derecha que late cada segundo— la Fase 17 COMPLETA —bitacora, editor de texto que persiste entre arranques en el grafo de objetos (tipografía 8×8 embebida)— y la Fase 18 COMPLETA —red: virtio-net + ARP al gateway de QEMU + recepción de paquetes registrada por COM1—. Todo verificado en QEMU. Ver ROADMAP.md.

Flujo de trabajo

En cada iteración de trabajo, sin excepción:

1. Actualizar CHANGELOG.md — la entrada técnica detallada del cambio.
2. Actualizar DIARIO.md — la misma jornada contada en lenguaje llano y elegante, sin carga técnica (es una crónica humana, no un registro técnico).
3. Verificar en QEMU si el cambio es observable (con captura de pantalla).
4. git commit (mensaje en español, descriptivo) y git push origin main.

renaser vive ahora dentro del monorepo brahman; los commits van al remoto de brahman (gitea.gioser.net/sergio/brahman). Mensajes de commit en español. Verifica una fase en QEMU antes de darla por cerrada.