1# ADR 0018 — Soberanía del arranque: convivir con otro gestor sin depender de su buena fe
2
3- **Estado:** PROPUESTO, con **§1 y §3 IMPLEMENTADOS y verificados en OVMF** (2026-09-11).
4  Queda **una decisión abierta** (§Secure Boot) y el §2/§4 por implementar.
5- **Fecha:** 2026-09-11
6- **Frontera:** `scripts/install-image-efi.sh`, `scripts/install-image.sh`, `scripts/iso-image.sh`,
7  `scripts/metal-usb-sdboot.sh`, `scripts/takana-live-install.sh`, el instalador TUI.
8- **Hermano:** [ADR 0017](0017-ciclo-de-vida-del-kernel.md). **Relacionado:**
9  [ADR 0010](0010-arranque-grafo-mirada.md), [SDD 27](../27-perfiles-instalables-y-el-instalador.md).
10
11## Contexto
12
13El caso es: el usuario tiene Windows y quiere takana al lado. Cada tanto Windows Update o el
14«Startup Repair» reordenan el arranque y takana deja de aparecer. El reflejo es tratarlo como un
15enemigo; es más útil y más productivo verlo por lo que es:
16
17> **La NVRAM del firmware es estado mutable compartido, y Windows es otro agente escribiendo en él
18> sin coordinarse con nadie.**
19
20Ese patrón este repo ya lo pagó dos veces: el índice de git es estado compartido (regla 2 de
21`CLAUDE.md`, commit `ff0b556`) y el árbol de fuentes es estado compartido ([ADR 0012](0012-arbol-de-fuentes-compartido-vs-privado.md)).
22La lección que costó las dos veces es la misma y se aplica igual acá:
23
24> No se resuelve pidiéndole al otro que se porte bien. Se resuelve con **reconciliación**, no con
25> **confianza**.
26
27Conviene además separar los dos modos de fallo, porque se arreglan distinto y se confunden siempre:
28
29- **El común (la enorme mayoría):** Windows **no borra nada**, te *desordena*. Reescribe `BootOrder`
30  poniéndose primero. Tu gestor sigue intacto; simplemente ya no es el que arranca.
31- **El feo:** algo **pisa el fichero**. Y ahí takana está hoy expuesta por diseño propio, no por
32  culpa de Windows.
33
34## Lo medido (2026-09-11)
35
36| qué | resultado |
37|---|---|
38| apariciones de `efibootmgr` en `scripts/` y `crates/` | **0** |
39| receta `efibootmgr`, `efivar` en el catálogo | **no existen** |
40| scripts que escriben `\EFI\BOOT\BOOTX64.EFI` | **5** (`install-image-efi.sh:190`, `install-image.sh`, `iso-image.sh`, `metal-usb-sdboot.sh:64`, `takana-live-install.sh`) |
41| entradas NVRAM que takana crea | **ninguna, nunca** |
42| el instalador live en UEFI, ¿respeta particiones existentes? | **no**: particiona el disco ENTERO en MBR (`takana-live-install.sh:286-292`) ⇒ **hoy no existe el caso «instalar al lado de Windows»**, no es que esté frágil |
43
44**El hallazgo que ordena todo el ADR:** takana **jamás crea una entrada de arranque**. Depende
45íntegramente de `\EFI\BOOT\BOOTX64.EFI`, que **por especificación UEFI es la ruta de medios
46removibles** — el último recurso que prueba el firmware cuando no encuentra nada más. Es tierra de
47nadie: la usa cualquier USB, la repueblan varias rutas de recuperación de Windows, y no le pertenece
48a ningún sistema instalado.
49
50Para un USB de bringup eso es **correcto**: es literalmente su lugar. Para una instalación en disco
51que comparte firmware con otro sistema operativo es **la peor dirección posible**, y hoy los dos
52casos comparten script.
53
54## Decisión
55
56### 1. Dos casos, dos rutas — y dejan de compartir código
57
58- **Medio removible (USB, ISO):** sigue en `\EFI\BOOT\BOOTX64.EFI`. Es su lugar por especificación.
59- **Instalación en disco:** vendor path propio **`\EFI\takana\takanax64.efi`** + entrada NVRAM
60  creada explícitamente. Deja de haber colisión de nombres con nadie.
61
62### 2. Estado de arranque **declarado** + reconciliador idempotente
63
64Takana declara cómo debe verse su arranque —vendor path, entrada NVRAM, posición en `BootOrder`— y
65**en cada arranque converge la NVRAM hacia esa declaración**. Corre siempre, no sólo cuando hay
66sospecha. Windows te desordena el lunes; el martes takana lo deshace.
67
68Y —esto no es opcional— **el reconciliador reporta que tuvo que actuar**. Si repara en silencio, el
69usuario vive con una rareza intermitente que nunca entiende. Un ausente falla ruidosamente; un
70arreglo mudo se parece demasiado a que no pasó nada (regla 3 de `CLAUDE.md`).
71
72### 3. La segunda pata, porque el reconciliador tiene huevo y gallina
73
74Si Windows deja a takana de último, **takana no arranca, y entonces el reconciliador nunca corre**.
75Hace falta algo que no dependa de haber arrancado:
76
77- **Dos punteros al mismo artefacto.** Vendor path (el de verdad) **y** una copia en la ruta
78  fallback como red. Es content-addressed: **el mismo kernel, dos entradas, coste marginal cero**.
79  Si Windows pisa la fallback, sobrevive la vendor; si desordena la NVRAM, en varios firmwares la
80  fallback todavía salva.
81- **La tecla del menú de arranque del firmware, como parte del contrato del instalador.** Suena
82  tonto. Es lo único que funciona cuando todo lo demás falló, y **ninguna distro te lo dice antes de
83  que lo necesites** — te lo dice un foro, a las dos de la mañana, desde otro dispositivo.
84
85> **ENMIENDA 2026-09-11 — implementado el §3 en las dos imágenes, y la medición corrigió el alcance.**
86>
87> `install-image-efi.sh` y `takana-live-install.sh` escriben ya el kernel en las **dos** rutas, con
88> guardián de capacidad previo. Verificado construyendo una imagen real y arrancándola en OVMF:
89>
90> | prueba | resultado |
91> |---|---|
92> | las dos copias en la ESP vs el bzImage del store | **sha256 idéntico** (`162cd18e4f8f1f5c`), 15 299 584 B cada una |
93> | arranque de la imagen completa | ✅ `HAMMER-EFI-DISK-PIVOT-OK` → `HAMMER-EFI-INIT-OK: arje-zero PID1` |
94> | **control negativo:** pisar `\EFI\BOOT\BOOTX64.EFI` con 4 KiB de basura, sin otra vía | ✅ `BdsDxe: No bootable option or device was found` — **cero** apariciones de `HAMMER-EFI` |
95>
96> El control negativo es el que da valor al resto: confirma que **pisar la ruta fallback mata el
97> arranque por completo** cuando es el único camino. Es el escenario de Windows, reproducido.
98>
99> ⚠ **Y lo que NO se pudo verificar cambia el alcance del §3, así que va acá y no en una nota al
100> pie:** no se logró arrancar POR el vendor path. Sin entrada NVRAM el firmware no lo busca —OVMF
101> cayó en `No bootable option` con el kernel intacto en `\EFI\takana\takanax64.efi`— y no hay
102> forma de crear esa entrada desde este hub (`efibootmgr` existe en el host pero escribe en la NVRAM
103> **del host**, no en un fichero `OVMF_VARS`; no hay `virt-firmware`; este OVMF no cae al UEFI Shell,
104> así que el truco del `startup.nsh` tampoco corre).
105>
106> ⇒ **La copia en el vendor path es un seguro que todavía no se puede cobrar solo.** Protege contra
107> que *pisen el fichero*, pero sólo si además existe la entrada NVRAM del §1. **El §3 es condición
108> necesaria y NO suficiente: sin el §1 la mitad del seguro falta.**
109>
110> **↳ CERRADO el mismo día por la enmienda de abajo.** El bloqueo se levantó, y no con `efibootmgr`.
111
112> **ENMIENDA 2026-09-11 (2ª) — el §1 está implementado y el arranque por vendor path está MEDIDO.**
113>
114> La entrada NVRAM la escribe takana, no `efibootmgr`. Se intentó primero la vía ajena y el muro se
115> midió: `efivar` 38 con musl/zig-cc choca con `secure_getenv` (no existe en musl), `sys/cdefs.h`
116> (tampoco) y `-Wl,--add-needed` (lld lo rechaza) — tres muros sólo para compilar su generador de
117> tablas, más `popt` arrastrado al sistema instalado. Lo que `efibootmgr` hace en el fondo es
118> **escribir dos ficheros** con una estructura de la spec UEFI estable desde la 2.0. Está en
119> `crates/takana-cli/src/efi_boot.rs` y se usa con `takana boot entry {list,add}`.
120>
121> **El experimento, que es lo que vale:** misma imagen de disco con la ruta fallback **pisada con
122> 4 KiB de basura**, dos corridas en OVMF que difieren **sólo** en la NVRAM.
123>
124> | corrida | NVRAM | resultado |
125> |---|---|---|
126> | control | limpia | `No bootable option or device was found` — cero líneas del initramfs |
127> | prueba | con la entrada que escribió takana | ✅ `BdsDxe: starting Boot0004 "takana" from HD(1,GPT,DA80800E-…,0x800,0x30000)/\EFI\takana\takanax64.efi` |
128>
129> El firmware imprime el device path que decodificó: `0x800` = LBA 2048 y `0x30000` = 196 608
130> sectores, **exactamente** los números que takana leyó del GPT. No es que «arrancó»: es que arrancó
131> **por la entrada que escribimos, con la fallback destruida**. Eso es el escenario de Windows con
132> el seguro cobrado.
133>
134> **Y la idempotencia del §2 quedó probada en condiciones reales**, no en un test: la segunda corrida
135> vuelve a ejecutar el reconciliador y dice «la entrada Boot0004 ya dice exactamente esto — no se
136> reescribe» y «BootOrder ya empieza por Boot0004 — no se toca». Importa más de lo que parece: la
137> NVRAM tiene un número finito de escrituras y esto está pensado para correr en cada arranque.
138>
139> De paso, el parser se validó contra **las cuatro entradas reales del firmware** (`BootManagerMenuApp`,
140> `EFI Firmware Setup`, `UEFI Misc Device`, `EFI Internal Shell`), que es un vector que nadie escribió
141> para que pasara la prueba.
142
143### 4. El instalador mira el terreno y lo dice en voz alta
144
145Antes de tocar nada: qué hay en la ESP, cuánto espacio libre queda, cómo está `BootOrder`, si hay un
146Windows Boot Manager. Reportar, no adivinar.
147
148Un fallo silencioso concreto que muerde mucho: **las ESP de fábrica son de 100 MB**, Windows las
149llena, y un bzImage con EFI-stub más su initramfs **no entra**. Eso tiene que fallar **ruidosamente
150y por adelantado**, con el número medido en pantalla — nunca truncar a mitad de instalación.
151
152### 5. Respaldo del arranque como artefacto sellado
153
154Volcar NVRAM (`efibootmgr -v`) + el contenido de la ESP al store en cada instalación y cada
155actualización de arranque. «Restaurar el arranque» pasa de adivinar a **reproducir un estado
156conocido**. Barato, y es exactamente la forma de takana.
157
158### 6. Lo que takana NO hace: `os-prober`
159
160No se escanean discos ajenos para adivinar qué sistemas hay y generar entradas. Es una fuente
161clásica de roturas y de menús que mienten. El firmware **ya tiene** un menú de arranque: takana pone
162su entrada, cuida su entrada, y no toca la del vecino.
163
164### 7. Las tres trampas del vecino, que no son del gestor de arranque
165
166Van en el manual del piloto (SDD 21) porque muerden a todo el mundo y no tienen que ver con el
167loader:
168
169- **BitLocker.** Tocar Secure Boot o el orden de arranque con BitLocker activo hace que Windows pida
170  la clave de recuperación de 48 dígitos en el siguiente arranque. **Suspenderlo antes.**
171- **Fast Startup.** Windows hiberna en vez de apagar: deja la ESP y la NTFS en estado sucio, y
172  montarlas desde Linux puede corromperlas. `powercfg /h off`.
173- **El reloj.** Windows escribe la RTC en hora local y Linux la espera en UTC. Cada cambio de
174  sistema desfasa el reloj — y acá un reloj mal puesto ensucia cualquier medición con marca de
175  tiempo, que es la mitad de la evidencia del proyecto.
176
177## Lo que no decide este ADR
178
179**¿Takana firma para Secure Boot?** ⛔ **ABIERTA.** Y no es cosmética: **ata con el
180[ADR 0017](0017-ciclo-de-vida-del-kernel.md)**, porque *lockdown* prohíbe el `kexec_load` viejo, que
181es el único que los seis kernels sellados soportan hoy.
182
183El caso de takana es **el más fácil que existe**: un único bzImage, sin módulos ⇒ una sola firma,
184cero infraestructura de firma de módulos.
185
186| opción | a favor | en contra |
187|---|---|---|
188| **shim + MOK** | cero fricción: el usuario no entra al firmware | dependencia de la cadena de confianza de Microsoft, en un proyecto cuyo eje es la soberanía |
189| **Claves propias** | soberano de punta a punta, coherente con el ADN del proyecto | el usuario entra al firmware a enrolar; hay que dejar enroladas las de Microsoft o Windows deja de arrancar |
190| **No firmar** | cero trabajo hoy | **le trasladás el costo al usuario**: desactivar Secure Boot con BitLocker activo = clave de recuperación de 48 dígitos. Y cierra `kexec` bajo lockdown |
191
192La tercera fila es la que suele elegirse por omisión y la que hay que mirar de frente: «no firmar» no
193es neutral, es **mover el costo a la persona que instala**.
194
195## Dependencias que este ADR crea
196
197- ~~Recetas nuevas: `efibootmgr` / `efivar`~~ — **resuelto sin dependencias nuevas**: la NVRAM la
198  escribe `takana boot entry add` (ver la 2ª enmienda). Si se decide firmar seguirá haciendo falta
199  `sbsigntool`, y `shim`/`mokutil` en la variante shim.
200- Los 5 scripts de arriba se parten en «medio removible» y «disco».
201- El instalador TUI gana el informe del terreno del §4.