# 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:

```sh
cd apps/<app>            # hello_wasm, discola, glotona, cronista, memoriosa, pulso, tonada
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— y la Fase 15 COMPLETA —la voz del sistema: acorde al
arrancar, repique al lanzar o cerrar, bajo al desalojar, con prioridad
sobre `sys_tono`—. 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.