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