1# ADR 0021 — El dueño del verbo de instalar: takana pone el motor, churay pone la cara
2
3- **Estado:** PROPUESTO, con la **parte de takana IMPLEMENTADA y medida** (2026-09-23). Lo de churay
4  es entrega, no está hecho.
5- **Fecha:** 2026-09-23
6- **Contesta:** [SDD 28 §8](../28-servidor-de-produccion.md) («`churay` como instalador centralizado
7  — la dirección, no la decisión»), que dejó tres preguntas anotadas para que se **decidieran** en
8  un ADR propio y no se descubrieran a mitad.
9- **Frontera:** `crates/takana-cli/src/metal.rs`, `scripts/takana-install-partition.sh`,
10  `scripts/instalador-initramfs.sh`, y —del otro lado— `02_ruway/churay` en tawasuyu.
11- **Relacionado:** [ADR 0017](0017-ciclo-de-vida-del-kernel.md) (kexec),
12  [ADR 0018](0018-soberania-del-arranque.md) (NVRAM), [ADR 0015](0015-imagenes-ajenas.md) (glibc),
13  [SDD 27](../27-perfiles-instalables-y-el-instalador.md) (perfiles instalables).
14
15## Contexto
16
17El instalador en metal quedó funcionando el 2026-09-23: censo del terreno, elección por PARTUUID,
18formateo de una sola partición, ESP poblada sin montarla, entrada NVRAM con respaldo previo, y el
19camino «sin USB» por `kexec`. Y aun así **no se podía usar**. La forma de invocarlo era ésta:
20
21```sh
22sudo ./takana kernel kexec ./kernel --initrd ./takana-instalador.cpio.gz \
23     --cmdline 'console=ttyS0,115200 console=tty0' --jump
24```
25
26El usuario lo dijo en una línea:
27
28> *pero esos son comandos a lo poweruser.*
29
30Tiene razón, y el diagnóstico es preciso: eso no es un instalador, es **el motor con la tapa
31abierta**. Quien lo teclea tiene que saber que existe `kexec`, que el payload va por `--initrd`, que
32sin `--jump` sólo se carga y qué consola pedirle al kernel nuevo. **Ninguna de esas cuatro cosas es
33una decisión del que instala** — son detalles de implementación que se filtraron a la superficie.
34
35Y la segunda mitad de su observación es la que importa para este ADR:
36
37> *churay era, la herramienta de instalar? ya tiene varias cosas adelantadas.*
38
39Sí. `churay` (quechua: *poner*) existe desde el 2026-06-24 en tawasuyu y está lejos de ser un
40esqueleto: instalador **por grafo** con GUI (`churay-llimphi`) y CLI (`churay-cli`), modo sistema y
41modo local, bundles precompilados firmados con ed25519, repo remoto multi-origen con clave anclada y
42anillo rotable, actualizador con `rollback`, vigía de espejos en cron, y una puerta de entrada desde
43la web (`tawasuyu.net/instalar.sh`). Lo que **no** hace es instalar takana en metal.
44
45Entonces la pregunta no es «¿hay que escribir un instalador?» sino **quién es dueño de qué**.
46
47## Decisión
48
49> **takana es dueño del MOTOR y expone un verbo estable. churay es dueño de la CARA y lo llama.
50> Ninguna cara vuelve a leer discos por su cuenta.**
51
52### 1. El verbo vive en takana, y es `takana metal`
53
54```
55takana metal check     ¿puede esta máquina instalarse sin USB?      (no toca nada)
56takana metal survey    ¿qué hay en los discos y qué se puede usar?  (no toca nada)
57takana metal install   el viaje entero: comprueba, avisa y salta
58```
59
60Tres verbos y el orden en que se usan es el orden en que se leen. `install` encuentra el paquete
61solo —junto al binario, no en el directorio actual, porque el paquete se copia a un pen drive y se
62corre desde cualquier lado—, corre el diagnóstico **antes** de prometer nada, dice en voz alta qué
63va a pasar y pide un «si» escrito. No acepta un *enter* pelado: el enter es lo que se aprieta sin
64leer, y lo que sigue mata la sesión.
65
66**Por qué en takana y no en churay.** El motor necesita root, `kexec_file_load`, dispositivos de
67bloque, las herramientas selladas del store y el rootfs ya construido. Nada de eso se puede mover a
68un instalador de usuario sin arrastrarlo entero. churay ya llegó a esa misma conclusión por su lado
69y lo dejó escrito en su LEEME: *«hammer-build/overlay (bwrap, zig, overlayfs, root) no encajan en un
70instalador de usuario, así que no se usan»*.
71
72### 2. El censo es UNO, y las caras lo consumen
73
74`takana metal survey` **no reimplementa nada**: ejecuta el mismo `takana-install-partition.sh
75--survey` que corre dentro del instalador. Con `--json` emite el contrato:
76
77```json
78{ "version": 1,
79  "raiz_viva": "8:2",
80  "particiones": [
81    {"dev": "/dev/sda2", "partuuid": "6F0B…", "mib": 6144, "fs": "ext4",
82     "etiqueta": "hammer-root", "montaje": "/", "veredicto": "RAIZ_VIVA",
83     "usable": true, "explicacion": "la raíz del sistema que está corriendo AHORA"} ] }
84```
85
86`veredicto` ∈ `CANDIDATA · LIBRE · RAIZ_VIVA · SOLO_ESP · EN_USO · NO_TOCAR`. El campo `usable` es
87la lectura de una sola pregunta —¿se puede instalar acá?— para que una cara **no tenga que
88reimplementar el `case` de los veredictos y equivocarse en el default**: lo que no reconozca no es
89usable.
90
91**Por qué esto es la parte que no se negocia.** El SDD 28 §8 ya nombra el riesgo —«un motor, tres
92frentes»— y este repo lo pagó dos veces (los `hydrate-*.sh` contra `targets.toml`; la unidad systemd
93del worker contra el repo). Acá el coste de divergir es peor que quedar desactualizado: **el censo
94es lo que decide qué NO se toca**. Una cara que clasifique por su cuenta y no conozca, por ejemplo,
95que una partición marcada LUKS en la tabla no se ofrece aunque `blkid` no vea cabecera adentro, no
96muestra de menos: **formatea de más**.
97
98### 3. Lo que churay hace, y lo que no
99
100| | churay | takana |
101|---|---|---|
102| pintar el terreno y preguntar | **sí** (consume `survey --json`) | modo texto, de respaldo |
103| decidir si una partición se puede tocar | **no** | sí, y es el único |
104| formatear, poblar la ESP, NVRAM | **no** | sí, dentro del instalador |
105| llegar a una máquina ajena (web, bundle, firma) | **sí, ya lo tiene** | no, y no lo va a tener |
106
107Lo último es el aporte real de churay y la razón por la que esto no es una capa de más: **el camino
108de la web al escritorio ya existe del lado de churay** —`instalar.sh`, `blobs/<hex>` verificados,
109manifiesto firmado, clave anclada, multi-origen, anillo rotable— y del lado de takana no existe
110ninguno. Hoy el paquete del instalador se copia a mano.
111
112## Las tres preguntas del SDD 28 §8, contestadas
113
114**(1) ¿Hidrata binarios o reproduce desde fuente en una máquina ajena?**
115Para **este** verbo, ninguna de las dos: el instalador **lleva el rootfs ya construido adentro**, en
116RAM, y lo copia. No hay build en la máquina del usuario y no hace falta red. La pregunta seguía
117teniendo sentido para *paquetes sueltos en cualquier distro*, que es otro verbo (`takana install`,
118SDD 27 §4) y **queda abierta ahí**. Confundirlas fue lo que hacía parecer que había una sola
119decisión.
120
121**(2) ¿Quién es dueño del verbo?** Contestado arriba: takana el motor, churay la cara. El verbo
122canónico es inglés (regla 4 de `CLAUDE.md`); lo que se lee, castellano.
123
124**(3) ¿Qué pasa con un host glibc?** **No es un problema, y hay que decir por qué para que nadie lo
125trate como si lo fuera.** Lo que el ADR 0015 aparta del store son *imágenes ajenas* —rootfs que no
126reproducen desde fuente—. Acá no entra nada al store: lo que corre en el host ajeno es **un ELF
127estático** (medido: `statically linked`, sin intérprete), así que el libc del anfitrión no
128participa. El instalador de verdad corre sobre **su propio kernel** después del salto, donde ya no
129hay host.
130
131## El salto, ejecutado de verdad (2026-09-23)
132
133Hasta este día el camino «sin USB» tenía **todo probado menos el salto**: el instalador en RAM se
134había arrancado a mano y hacía su trabajo, pero `kexec_file_load` **no se había ejecutado nunca** —
135ninguna de nuestras máquinas corre un kernel con `CONFIG_KEXEC_FILE`, así que el primer sitio donde
136el salto iba a pasar era la máquina del usuario. Eso convierte al usuario en el banco de pruebas.
137
138`scripts/metal-salto-test.sh` lo cierra: arranca una VM con `linux-metal-kexec` —la variante que sí
139trae el flag—, le da un disco con vecinos de verdad (una ESP con un `bootmgfw.efi` de Microsoft
140dentro, un destino vacío y un hueco sin asignar) y corre ahí **los tres verbos de usuario**. Las
141once comprobaciones en verde, y el veredicto sale del **disco**, no de lo que la pantalla dijo:
142
143```
144✓ el sistema origen arrancó            ✓ EL SALTO OCURRIÓ: el origen no volvió del kexec
145✓ metal check: dice que SÍ             ✓ el instalador arrancó DESPUÉS del salto
146✓ metal survey: el censo salió         ✓ el instalador terminó bien
147✓ metal install: anunció el salto      ✓ la tabla de particiones NO cambió
148✓ el destino quedó ext4 con LABEL=hammer-root
149✓ la ESP tiene \EFI\takana\takanax64.efi
150✓ el vecino de la ESP (bootmgfw.efi de Microsoft) quedó byte a byte igual
151```
152
153El log serial corta exactamente donde tiene que cortar —`⚡ saltando al instalador — esto no
154vuelve.`— y la línea siguiente ya es del otro kernel: `TAKANA-INSTALADOR: arrancado en RAM. El
155sistema viejo YA NO CORRE: su disco está libre.`
156
157⚠ Y el arnés nació con dos comprobaciones que fallaban **sin que el instalador tuviera nada que
158ver**, que es la forma más cara de tener un test: comparaba el listado de `mdir` del vecino contra sí
159mismo —y el listado trae el «bytes free» del volumen, que cambia en cuanto se copia cualquier otra
160cosa— y usaba `cmp`, que **no existe en este anfitrión musl**: `command not found` sale 127, el `if`
161lo toma como falso y el test acusaba «la tabla cambió» sin haber comparado nada. Un test que no
162puede correr tiene que decirlo, no fallar con el mensaje de otra cosa.
163
164## Lo medido (2026-09-23)
165
166| | |
167|---|---|
168| `metal check` como uid 1001 | dice «falta root», **y avisa que el diagnóstico no es concluyente** |
169| `metal check` como root del anfitrión | dice la causa real: el kernel no trae `CONFIG_KEXEC_FILE` |
170| `metal survey --json` en el hub | 6 entradas, JSON válido, una sola `usable` |
171| `metal install` sin paquete | nombra los tres directorios donde buscó |
172| `--unattended` sin destino | aborta: «nadie va a estar ahí para elegirlo» |
173| la cmdline sin respuestas | **idéntica al default**: no hay ninguna máquina horneada (test) |
174
175Dos defectos aparecieron al poner la cara, y los dos eran del motor:
176
177- **`--survey` exigía el kernel y mtools.** En una máquina ajena —sin store y sin kernel del
178  corpus— el censo moría con «no encuentro el kernel EFI-stub» **antes de imprimir una sola línea
179  del terreno**. Mirar no puede costar lo mismo que escribir.
180- **`--survey` salía con 1 habiendo funcionado.** Un `a && b && c` como último comando del bucle de
181  impresión decide el estado de salida del script entero; con `set -e`, `mostrar_censo` moría ahí si
182  la última fila no tenía PARTUUID (un disco sin tabla, un hueco libre). En este hub la última fila
183  es `/dev/sdc`. Un `if` no propaga; el `&&` sí.
184
185Y uno de clasificación, que es el que más se parece a lo que este ADR quiere evitar: el censo
186ofrecía `/dev/sda1` —**2 MiB**, el hueco de arranque— como «✓ se puede usar», porque el veredicto
187miraba **qué** hay dentro y nunca **cuánto** cabe. Elegirla formatea algo real y muere a mitad de la
188copia. El piso es ahora el mismo número con el que se talla un hueco (`mib_necesarios`), así que las
189dos puertas no pueden divergir.
190
191## Lo que este ADR NO decide
192
193- **Windows.** El instalador standalone desde Windows sigue donde lo dejó el runbook: WSL2 no tiene
194  efivarfs y un `.exe` nativo es un port, no una envoltura. churay tiene su propio frente ahí
195  (`PLAN-MULTIPLATAFORMA.md`, F4) y no se mezcla con éste.
196- **Firmar el kernel del instalador.** Con Secure Boot en modo `integrity` el salto no ocurre, y hoy
197  no firmamos. Es la decisión abierta del ADR 0018.
198- **Redimensionar.** Encoger un filesystem pide desmontarlo, y la raíz viva no se desmonta. Eso es
199  física, no una carencia: el redimensionado vive **después** del salto, dentro del instalador, y
200  todavía no está escrito.
201
202## Entrega a tawasuyu (churay)
203
204Lo que hace falta del otro lado, en orden, y nada de esto toca takana:
205
2061. Un nodo `takana (sistema en metal)` en el grafo, con `Scope::System`, que **no** se instala como
207   los demás: al activarlo abre la pantalla del terreno.
2082. Esa pantalla se pinta con `takana metal survey --json`. Las particiones con `usable: false` se
209   muestran —el usuario tiene que ver su disco entero— pero no se pueden elegir, y se muestra su
210   `explicacion` tal cual: está escrita para leerse.
2113. El botón llama a `takana metal install --root PARTUUID=… [--esp PARTUUID=…] --unattended --yes`,
212   y **avisa antes de que la sesión gráfica muere en el salto**.
2134. Si `takana metal check` sale ≠ 0, la pantalla ofrece el USB en vez del salto, mostrando los
214   motivos que imprime, que ya están redactados para el usuario.
215
216El binario `takana` que churay necesita es el estático, el mismo que ya viaja en el paquete del
217instalador. churay no necesita el store, ni el rootfs, ni root para el `survey` — sólo para el
218`install`, que ya sabe pedirlo.