takana/docs/adr/0018-soberania-del-arranque.md

# ADR 0018 — Soberanía del arranque: convivir con otro gestor sin depender de su buena fe

- **Estado:** PROPUESTO, con **§1 a §5 IMPLEMENTADOS y verificados** (2026-09-11/12).
  Queda **una decisión abierta** (§Secure Boot); el §6 es una no-acción deliberada y el §7 va al
  manual del piloto (SDD 21).
- **Fecha:** 2026-09-11
- **Frontera:** `scripts/install-image-efi.sh`, `scripts/install-image.sh`, `scripts/iso-image.sh`,
  `scripts/metal-usb-sdboot.sh`, `scripts/takana-live-install.sh`, el instalador TUI.
- **Hermano:** [ADR 0017](0017-ciclo-de-vida-del-kernel.md). **Relacionado:**
  [ADR 0010](0010-arranque-grafo-mirada.md), [SDD 27](../27-perfiles-instalables-y-el-instalador.md).

## Contexto

El caso es: el usuario tiene Windows y quiere takana al lado. Cada tanto Windows Update o el
«Startup Repair» reordenan el arranque y takana deja de aparecer. El reflejo es tratarlo como un
enemigo; es más útil y más productivo verlo por lo que es:

> **La NVRAM del firmware es estado mutable compartido, y Windows es otro agente escribiendo en él
> sin coordinarse con nadie.**

Ese patrón este repo ya lo pagó dos veces: el índice de git es estado compartido (regla 2 de
`CLAUDE.md`, commit `ff0b556`) y el árbol de fuentes es estado compartido ([ADR 0012](0012-arbol-de-fuentes-compartido-vs-privado.md)).
La lección que costó las dos veces es la misma y se aplica igual acá:

> No se resuelve pidiéndole al otro que se porte bien. Se resuelve con **reconciliación**, no con
> **confianza**.

Conviene además separar los dos modos de fallo, porque se arreglan distinto y se confunden siempre:

- **El común (la enorme mayoría):** Windows **no borra nada**, te *desordena*. Reescribe `BootOrder`
  poniéndose primero. Tu gestor sigue intacto; simplemente ya no es el que arranca.
- **El feo:** algo **pisa el fichero**. Y ahí takana está hoy expuesta por diseño propio, no por
  culpa de Windows.

## Lo medido (2026-09-11)

| qué | resultado |
|---|---|
| apariciones de `efibootmgr` en `scripts/` y `crates/` | **0** |
| receta `efibootmgr`, `efivar` en el catálogo | **no existen** |
| 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`) |
| entradas NVRAM que takana crea | **ninguna, nunca** |
| 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 |

**El hallazgo que ordena todo el ADR:** takana **jamás crea una entrada de arranque**. Depende
íntegramente de `\EFI\BOOT\BOOTX64.EFI`, que **por especificación UEFI es la ruta de medios
removibles** — el último recurso que prueba el firmware cuando no encuentra nada más. Es tierra de
nadie: la usa cualquier USB, la repueblan varias rutas de recuperación de Windows, y no le pertenece
a ningún sistema instalado.

Para un USB de bringup eso es **correcto**: es literalmente su lugar. Para una instalación en disco
que comparte firmware con otro sistema operativo es **la peor dirección posible**, y hoy los dos
casos comparten script.

## Decisión

### 1. Dos casos, dos rutas — y dejan de compartir código

- **Medio removible (USB, ISO):** sigue en `\EFI\BOOT\BOOTX64.EFI`. Es su lugar por especificación.
- **Instalación en disco:** vendor path propio **`\EFI\takana\takanax64.efi`** + entrada NVRAM
  creada explícitamente. Deja de haber colisión de nombres con nadie.

### 2. Estado de arranque **declarado** + reconciliador idempotente

Takana declara cómo debe verse su arranque —vendor path, entrada NVRAM, posición en `BootOrder`— y
**en cada arranque converge la NVRAM hacia esa declaración**. Corre siempre, no sólo cuando hay
sospecha. Windows te desordena el lunes; el martes takana lo deshace.

Y —esto no es opcional— **el reconciliador reporta que tuvo que actuar**. Si repara en silencio, el
usuario vive con una rareza intermitente que nunca entiende. Un ausente falla ruidosamente; un
arreglo mudo se parece demasiado a que no pasó nada (regla 3 de `CLAUDE.md`).

> **ENMIENDA 2026-09-11 (3ª) — el §2 está implementado, y lo caro no fue el reconciliador.**
>
> `takana boot entry reconcile` descubre su propia ESP por **tipo de partición** (GUID de ESP en GPT,
> `0xEF` en MBR), que es el único dato fiable sin montar nada. Si hay **varias** ESP no adivina: las
> lista y pide `--disk`. Elegir mal significa escribir una entrada que apunta a un disco que puede no
> estar, y eso es peor que no escribir nada. Corre desde el wrapper de PID1 de las dos imágenes, y
> cuando actúa **grita a `/dev/tty0` además del serial** — un reconciliador que repara en silencio
> deja al usuario conviviendo con una rareza que no entiende.
>
> **Lo que costó el tiempo fue un diagnóstico falso, y vale más que el código:** el primer arranque
> con el hook puesto imprimió
>
> > `boot entry reconcile: sin firmware EFI en /sys/firmware/efi/efivars — nada que hacer`
> > `(esta máquina no arrancó por UEFI)`
>
> **en una VM que había arrancado por UEFI.** La causa no tenía nada que ver con UEFI:
> `busybox switch_root` **no arrastra `/sys`** —igual que no arrastra `/dev`, cosa que el script ya
> contemplaba con su `mount -t devtmpfs`— así que `/sys/firmware/efi/efivars` sencillamente no
> existía. El mensaje mandaba a investigar el firmware, que estaba perfecto.
>
> **Verificado después en la máquina real, dos arranques seguidos de la imagen completa:**
>
> | arranque | qué hizo | salida |
> |---|---|---|
> | 1º (por la ruta fallback) | detectó su ESP **solo** y vio que faltaba la entrada | `ESP detectada en /dev/vda p1` · `⚠ EL ARRANQUE ESTABA CAMBIADO — takana lo repuso` · `faltaba la entrada «takana» ⇒ escrita en Boot0004` · `BootOrder: 0000,0001,0002,0003 → 0004,0000,…` |
> | 2º (sin tocar nada) | **el firmware arrancó por la entrada que se escribió sola** | `BdsDxe: starting Boot0004 "takana" from HD(1,GPT,923A070F-…)/\EFI\takana\takanax64.efi` · `✓ arranque en orden: Boot0004 «takana» ya es la primera` |
>
> O sea: un sistema recién instalado **se da de alta en el firmware en su primer arranque** y a
> partir del segundo arranca por su propia entrada, sin que nadie corra un comando. Y el segundo
> arranque no escribe nada.
>
> Dos arreglos, y el segundo importa tanto como el primero:
> 1. El wrapper monta `sysfs` y después `efivarfs`. El kernel ya traía `CONFIG_EFIVAR_FS=y`
>    —verificado en el `.config` **sellado**, no supuesto—, así que no se re-hashea nada.
> 2. El mensaje distingue ahora **tres** estados que se parecen: el directorio no existe (BIOS, o
>    `/sys` sin montar), existe y está **vacío** (falta el `mount`, y lo dice con el comando exacto),
>    o tiene variables. Decir «no hay UEFI» cuando lo que falta es un `mount` manda a diagnosticar al
>    lugar equivocado — y el que se equivocó primero fue este ADR.

### 3. La segunda pata, porque el reconciliador tiene huevo y gallina

Si Windows deja a takana de último, **takana no arranca, y entonces el reconciliador nunca corre**.
Hace falta algo que no dependa de haber arrancado:

- **Dos punteros al mismo artefacto.** Vendor path (el de verdad) **y** una copia en la ruta
  fallback como red. Es content-addressed: **el mismo kernel, dos entradas, coste marginal cero**.
  Si Windows pisa la fallback, sobrevive la vendor; si desordena la NVRAM, en varios firmwares la
  fallback todavía salva.
- **La tecla del menú de arranque del firmware, como parte del contrato del instalador.** Suena
  tonto. Es lo único que funciona cuando todo lo demás falló, y **ninguna distro te lo dice antes de
  que lo necesites** — te lo dice un foro, a las dos de la mañana, desde otro dispositivo.

> **ENMIENDA 2026-09-11 — implementado el §3 en las dos imágenes, y la medición corrigió el alcance.**
>
> `install-image-efi.sh` y `takana-live-install.sh` escriben ya el kernel en las **dos** rutas, con
> guardián de capacidad previo. Verificado construyendo una imagen real y arrancándola en OVMF:
>
> | prueba | resultado |
> |---|---|
> | las dos copias en la ESP vs el bzImage del store | **sha256 idéntico** (`162cd18e4f8f1f5c`), 15 299 584 B cada una |
> | arranque de la imagen completa | ✅ `HAMMER-EFI-DISK-PIVOT-OK` → `HAMMER-EFI-INIT-OK: arje-zero PID1` |
> | **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` |
>
> El control negativo es el que da valor al resto: confirma que **pisar la ruta fallback mata el
> arranque por completo** cuando es el único camino. Es el escenario de Windows, reproducido.
>
> ⚠ **Y lo que NO se pudo verificar cambia el alcance del §3, así que va acá y no en una nota al
> pie:** no se logró arrancar POR el vendor path. Sin entrada NVRAM el firmware no lo busca —OVMF
> cayó en `No bootable option` con el kernel intacto en `\EFI\takana\takanax64.efi`— y no hay
> forma de crear esa entrada desde este hub (`efibootmgr` existe en el host pero escribe en la NVRAM
> **del host**, no en un fichero `OVMF_VARS`; no hay `virt-firmware`; este OVMF no cae al UEFI Shell,
> así que el truco del `startup.nsh` tampoco corre).
>
> ⇒ **La copia en el vendor path es un seguro que todavía no se puede cobrar solo.** Protege contra
> que *pisen el fichero*, pero sólo si además existe la entrada NVRAM del §1. **El §3 es condición
> necesaria y NO suficiente: sin el §1 la mitad del seguro falta.**
>
> **↳ CERRADO el mismo día por la enmienda de abajo.** El bloqueo se levantó, y no con `efibootmgr`.

> **ENMIENDA 2026-09-11 (2ª) — el §1 está implementado y el arranque por vendor path está MEDIDO.**
>
> La entrada NVRAM la escribe takana, no `efibootmgr`. Se intentó primero la vía ajena y el muro se
> midió: `efivar` 38 con musl/zig-cc choca con `secure_getenv` (no existe en musl), `sys/cdefs.h`
> (tampoco) y `-Wl,--add-needed` (lld lo rechaza) — tres muros sólo para compilar su generador de
> tablas, más `popt` arrastrado al sistema instalado. Lo que `efibootmgr` hace en el fondo es
> **escribir dos ficheros** con una estructura de la spec UEFI estable desde la 2.0. Está en
> `crates/takana-cli/src/efi_boot.rs` y se usa con `takana boot entry {list,add}`.
>
> **El experimento, que es lo que vale:** misma imagen de disco con la ruta fallback **pisada con
> 4 KiB de basura**, dos corridas en OVMF que difieren **sólo** en la NVRAM.
>
> | corrida | NVRAM | resultado |
> |---|---|---|
> | control | limpia | `No bootable option or device was found` — cero líneas del initramfs |
> | prueba | con la entrada que escribió takana | ✅ `BdsDxe: starting Boot0004 "takana" from HD(1,GPT,DA80800E-…,0x800,0x30000)/\EFI\takana\takanax64.efi` |
>
> El firmware imprime el device path que decodificó: `0x800` = LBA 2048 y `0x30000` = 196 608
> sectores, **exactamente** los números que takana leyó del GPT. No es que «arrancó»: es que arrancó
> **por la entrada que escribimos, con la fallback destruida**. Eso es el escenario de Windows con
> el seguro cobrado.
>
> **Y la idempotencia del §2 quedó probada en condiciones reales**, no en un test: la segunda corrida
> vuelve a ejecutar el reconciliador y dice «la entrada Boot0004 ya dice exactamente esto — no se
> reescribe» y «BootOrder ya empieza por Boot0004 — no se toca». Importa más de lo que parece: la
> NVRAM tiene un número finito de escrituras y esto está pensado para correr en cada arranque.
>
> De paso, el parser se validó contra **las cuatro entradas reales del firmware** (`BootManagerMenuApp`,
> `EFI Firmware Setup`, `UEFI Misc Device`, `EFI Internal Shell`), que es un vector que nadie escribió
> para que pasara la prueba.

### 4. El instalador mira el terreno y lo dice en voz alta

Antes de tocar nada: qué hay en la ESP, cuánto espacio libre queda, cómo está `BootOrder`, si hay un
Windows Boot Manager. Reportar, no adivinar.

Un fallo silencioso concreto que muerde mucho: **las ESP de fábrica son de 100 MB**, Windows las
llena, y un bzImage con EFI-stub más su initramfs **no entra**. Eso tiene que fallar **ruidosamente
y por adelantado**, con el número medido en pantalla — nunca truncar a mitad de instalación.

> **ENMIENDA 2026-09-11 (4ª) — el §4 implementado: `takana boot entry survey`.**
>
> Reporta firmware, discos, ESPs, con quién se comparten y si la instalación entra. **No escribe
> nada** — y para poder prometer eso hubo que leer la ESP **sin montarla**, que es lo que obligó a
> escribir un lector FAT de sólo lectura (`crates/takana-cli/src/fat_ro.rs`). Montar para averiguarlo
> tenía tres problemas: pide privilegios, deja un efecto secundario justo cuando prometimos no tocar
> nada, y falla si el vecino dejó la FAT sucia por su hibernación (el «Fast Startup» del §7).
>
> Sobre una ESP de fábrica (100 MiB) con Windows dentro y el kernel duplicado a instalar:
>
> ```
>   FAT32 «ESP» — 100.0 MiB totales, 77.1 MiB usados, 22.1 MiB libres
>   vecinos en \EFI: Microsoft, BOOT
>     ⚠ «Microsoft» ⇒ hay Windows en esta ESP. Es el que reordena BootOrder al actualizarse.
>   ✗ NO ENTRA: hacen falta 31.0 MiB y hay 22.1 MiB libres
>   ── veredicto ──
>   ✗ …p1: faltan 8.9 MiB en la ESP
> ```
>
> **Contrastado contra `mtools` como oráculo**, que es lo que hace que el número sea creíble: `mdir`
> reporta `23 221 248 bytes free` y el lector propio dice 22,1 MiB — el mismo número. Los clusters
> libres se cuentan recorriendo la FAT y **no** se lee el `FSInfo` de FAT32 a propósito: ese campo es
> una pista que un sistema operativo que desmontó mal deja desactualizada, y un número optimista de
> más haría fallar la instalación a mitad, que es exactamente lo que este §4 existe para evitar.
>
> **Y en el instalador el §4 resultó ser algo más que «cuánto espacio hay».** La rama UEFI se lleva
> el disco **entero** (§Lo medido), así que lo que hay que decir en voz alta es **con qué se lo va a
> llevar puesto**: el survey corre antes de particionar y, si hay un `\EFI\Microsoft` en ese disco,
> lo nombra. El usuario se entera **antes**, y no después de que su Windows dejó de arrancar.
>
> Dos detalles que habrían pasado inadvertidos sin un test:
> - **El nombre largo tiene que ganarle al 8.3.** Sin juntar los LFN, `Microsoft` se lee `MICROS~1` y
>   la advertencia —la razón de ser de esto— no dispara nunca.
> - **El tipo de FAT sale del número de clusters, no del texto del BPB**, que es informativo y hay
>   formateadores que mienten en él. (El primer test que escribí para esto estaba mal calculado:
>   1999 clusters *es* FAT12. El que fallaba era el test, y el síntoma es idéntico a un bug del
>   lector.)

### 5. Respaldo del arranque como artefacto sellado

Volcar NVRAM (`efibootmgr -v`) + el contenido de la ESP al store en cada instalación y cada
actualización de arranque. «Restaurar el arranque» pasa de adivinar a **reproducir un estado
conocido**. Barato, y es exactamente la forma de takana.

> **ENMIENDA 2026-09-11 (5ª) — el §5 implementado, y el ADR se equivocaba en DÓNDE guardarlo.**
>
> `takana boot entry backup` / `restore`. El respaldo guarda las variables de NVRAM **crudas** —se
> reescriben tal cual; decodificarlas para volver a codificarlas al restaurar sería una oportunidad
> de perder algo que no entendemos— y de la ESP un **manifiesto con hashes**, no los bytes: el kernel
> ya vive en el store y copiarlo otra vez sería churn. El manifiesto es **evidencia de qué había**;
> para lo que no esté en el store dice qué falta, en vez de prometer que lo puede reponer.
>
> **Corrección al §5 tal como estaba escrito:** decía «volcar al store». **No va al store.** Lo barre
> `store-gc.sh`, que clasifica por nombre de receta: un respaldo ahí sería *huérfano* y se borraría
> en el primer `--huerfanos`. Vive en `/var/lib/hammer/boot/`, que en las imágenes es **su propia
> partición** y sobrevive a una reinstalación del sistema. El nombre del fichero sale del
> **contenido**, así que un arranque que no cambió produce el mismo fichero y esto puede correr en
> cada arranque sin llenar la partición de estado con copias idénticas.
>
> **Lo que encontró la prueba de punta a punta, y que no estaba en el diseño:** restaurar es volver
> al pasado, **y lo que llegó después no estaba en ese pasado**. Al reponer el `BootOrder` del
> respaldo, el Windows instalado *más tarde* quedaba **fuera del orden** — semánticamente correcto y
> exactamente lo que el usuario no espera de algo llamado «restaurar el arranque». Ahora se avisa
> antes, con nombre y apellido:
>
> ```
>   ⚠ ESTO SACA DE BootOrder a 1 entrada(s) que hoy sí están:
>       Boot0001 «Windows Boot Manager»
>     Son las que aparecieron DESPUÉS del respaldo. Si alguna es otro sistema
>     operativo, va a dejar de arrancar desde el menú del firmware hasta que la repongas.
> ```
>
> Y `restore` **no escribe por defecto**: hay que pasar `--apply`. La NVRAM es lo único de la máquina
> que no se puede rehacer desde el store.
>
> El lector FAT ganó lectura de ficheros para el manifiesto, con su trampa propia: **hay que truncar
> al tamaño declarado en el directorio**, no al final del último cluster. Un fichero de 1,5 MB en
> clusters de 1 KiB termina con relleno, y hashear el relleno daría un hash distinto al del mismo
> fichero en disco — el síntoma sería «dos respaldos del mismo arranque difieren». Verificado contra
> `mtools` como oráculo (extrae 1 500 000 y 900 000 bytes exactos, mismo sha256 que los originales) y
> con un test determinista que fabrica una FAT16 a mano, sin depender de que mtools esté.

### 6. Lo que takana NO hace: `os-prober`

No se escanean discos ajenos para adivinar qué sistemas hay y generar entradas. Es una fuente
clásica de roturas y de menús que mienten. El firmware **ya tiene** un menú de arranque: takana pone
su entrada, cuida su entrada, y no toca la del vecino.

### 7. Las tres trampas del vecino, que no son del gestor de arranque

Van en el manual del piloto (SDD 21) porque muerden a todo el mundo y no tienen que ver con el
loader:

- **BitLocker.** Tocar Secure Boot o el orden de arranque con BitLocker activo hace que Windows pida
  la clave de recuperación de 48 dígitos en el siguiente arranque. **Suspenderlo antes.**
- **Fast Startup.** Windows hiberna en vez de apagar: deja la ESP y la NTFS en estado sucio, y
  montarlas desde Linux puede corromperlas. `powercfg /h off`.
- **El reloj.** Windows escribe la RTC en hora local y Linux la espera en UTC. Cada cambio de
  sistema desfasa el reloj — y acá un reloj mal puesto ensucia cualquier medición con marca de
  tiempo, que es la mitad de la evidencia del proyecto.

## Lo que no decide este ADR

**¿Takana firma para Secure Boot?** ⛔ **ABIERTA.** Y no es cosmética: **ata con el
[ADR 0017](0017-ciclo-de-vida-del-kernel.md)**, porque *lockdown* prohíbe el `kexec_load` viejo, que
es el único que los seis kernels sellados soportan hoy.

El caso de takana es **el más fácil que existe**: un único bzImage, sin módulos ⇒ una sola firma,
cero infraestructura de firma de módulos.

| opción | a favor | en contra |
|---|---|---|
| **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 |
| **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 |
| **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 |

La tercera fila es la que suele elegirse por omisión y la que hay que mirar de frente: «no firmar» no
es neutral, es **mover el costo a la persona que instala**.

## Dependencias que este ADR crea

- ~~Recetas nuevas: `efibootmgr` / `efivar`~~ — **resuelto sin dependencias nuevas**: la NVRAM la
  escribe `takana boot entry add` (ver la 2ª enmienda). Si se decide firmar seguirá haciendo falta
  `sbsigntool`, y `shim`/`mokutil` en la variante shim.
- Los 5 scripts de arriba se parten en «medio removible» y «disco».
- El instalador TUI gana el informe del terreno del §4.