1# renaser ↔ brahman — integración en el monorepo
2
3`renaser` es un kernel bare-metal SASOS (espacio de direcciones único,
4no-POSIX, `no_std`, x86_64). Vive en `renaser/` dentro de este repo. Este
5documento explica **cómo** convive con brahman y **qué** comparten.
6
7## Por qué un workspace de Cargo aparte
8
9renaser está en el mismo repo git pero es **su propio workspace de Cargo** —
10no un miembro del de brahman. Tres incompatibilidades lo imponen:
11
12| | brahman | renaser |
13| --- | --- | --- |
14| toolchain | `stable` | `nightly` (artifact-deps, `rust-src`) |
15| `panic` | unwind (lo necesita tokio) | `abort` (sin SO no hay unwinding) |
16| `cargo build` en la raíz | compila todo para el host | el kernel jamás debe compilarse para el host |
17
18`[profile]` y `rust-toolchain.toml` son **globales al workspace**: no se pueden
19mezclar. Por eso `brahman/Cargo.toml` lleva `exclude = ["renaser"]` y
20`renaser/Cargo.toml` es un `[workspace]` raíz independiente, con su propio
21`rust-toolchain.toml` y `.cargo/`. Cargo los trata como ajenos; los crates
22compartidos se referencian por `path` cruzando la frontera.
23
24## El modelo: núcleos duales, superficies por-plataforma
25
26La integración **no** es «cada crate compila para los dos lados». Es:
27
28- **Núcleos** — lógica pura (`*-core`, geometría, contratos). Se hacen
29  `no_std + alloc` y se comparten: el mismo crate compila para Linux y para
30  `x86_64-unknown-none`.
31- **Superficies** — IO y plataforma (daemons tokio, `sled`, gpui, smithay,
32  init con `nix`/`libc`; del lado renaser, el kernel y sus drivers). **No** se
33  comparten: cada plataforma tiene la suya. renaser no «importa» smithay;
34  provee su propio framebuffer.
35
36Un crate gana el tratamiento `no_std` **sólo cuando renaser de verdad lo
37enlaza**. La mayoría de brahman (apps gpui, ERP, transpilador, daemons) nunca
38corre en renaser y se queda `std`.
39
40## Núcleos compartidos
41
42| crate | rol | consumidor renaser |
43| --- | --- | --- |
44| `mirada-layout` | motor de teselado del compositor (geometría pura) | kernel, Fase 8 (compositor) |
45
46Cómo se hace `no_std` un núcleo (patrón de `mirada-layout`):
47
481. `#![cfg_attr(not(test), no_std)]` + `extern crate alloc;` — los tests
49   siguen corriendo con `std`; el crate enviado es `no_std`.
502. `std::collections` → `alloc::collections`; `Vec`/`vec!` → `use alloc::…`.
513. Punto flotante (`sqrt`/`ceil`/`round`) → crate `libm` (no están en `core`).
524. `serde` opcional tras una feature: los consumidores Linux la activan, el
53   kernel no.
545. Dependencias declaradas directas (no `workspace = true`): un núcleo que
55   cruza fronteras de workspace se mantiene autocontenido.
56
57### El guardián
58
59`scripts/check-shared-cores.sh` compila cada núcleo registrado para
60`x86_64-unknown-none`. Si un núcleo recobra `std` (p. ej. al añadir una
61dependencia descuidada), falla ahí. **Correrlo tras tocar un núcleo
62compartido.** Al promover un crate nuevo, añadirlo al array `CORES` del script.
63
64## Plan por etapas — estado
65
66- **Paso 0 ✅** — renaser movido a `renaser/`, workspace propio, `exclude`.
67- **Paso 1 ✅** — `mirada-layout` → `no_std`; el kernel de renaser lo
68  `path`-depende cruzando workspaces. Mecanismo validado.
69- **Paso 2 — descartado.** El plan era «converger el CAS». Al leer el código
70  no se sostiene: son **tres capas distintas**, no una duplicación.
71  - `arje-cas` — blobs SHA256 sobre el sistema de archivos. SHA256 lo fija el
72    contrato `Card` (`module_sha256`); es una *superficie* Linux.
73  - `renaser/almacen` — DAG de objetos (payload + hijos), hash
74    `blake3(postcard)`, log sobre virtio-blk. Es una *superficie* bare-metal.
75  - `minga-core` — Merkle-AST con hash **estructural** (`hash_components`,
76    campo a campo, no `blake3(postcard)`): un esquema deliberadamente
77    distinto que permite verificar un nodo sin los bytes de sus hijos.
78  - Forzar un núcleo común impondría una abstracción equivocada (romper la
79    verificación estructural de minga, o cambiar el SHA256 del protocolo
80    `Card`). Lo único común —un newtype de hash de 32 bytes— no justifica
81    tocar el kernel verificado.
82- **Paso 4 ✅** — el guardián `no_std` (`scripts/check-shared-cores.sh`).
83- **wasmi unificado ✅** — brahman y renaser corren ambos `wasmi 1.0`
84  (`arje-wasm` migrado de `0.40`). El ABI WASM del host es ahora la misma
85  versión en Linux y en bare-metal.
86- **Paso 3 — pendiente, ya desbloqueado.** Converger el ABI `Card`/WASM:
87  la matriz `sys_*` de capacidades de renaser y el contrato `Card` de
88  brahman aún son universos paralelos. Es trabajo de diseño (qué forma
89  toma una capacidad compartida), no un bump mecánico.
90
91Fase 8 de renaser (su propia hoja de ruta): el kernel usa `mirada-layout` para
92el compositor, con su framebuffer nativo.
93
94## Construir
95
96- brahman: `cargo build` en la raíz (ignora `renaser/`).
97- renaser: `cd renaser && cargo build -p boot` (kernel + imagen UEFI) o
98  `cargo run -p boot` (+ QEMU). Toma su toolchain nightly automáticamente.
99- guardián: `./scripts/check-shared-cores.sh`.