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 la app WASM del userspace tras tocar apps/hello_wasm:

cd apps/hello_wasm
cargo build --target wasm32-unknown-unknown --release
cp target/wasm32-unknown-unknown/release/hello_wasm.wasm ../../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, baliza, sync, gdt, interrupts, pic, drivers/, almacen, 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, la 6.0, la 6.1 completa (sustrato de almacenamiento: sonda PCI, HAL/DMA y el grafo de objetos) y la 6.2 (E/S de disco asíncrona por interrupción) completadas y verificadas 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.

El remoto origin es gitea.gioser.net/sergio/renaser. Mensajes de commit en español. Verifica una fase en QEMU antes de darla por cerrada.