1# SDD 21 — Manual del piloto: qué hago yo, paso a paso
2
3Escrito 2026-08-07, a pedido del usuario: «un tipo manual, todos los pasos que tengo que ir haciendo
4en las tres etapas que marcan esos dos codos».
5
6El inventario de lo que falta está en el [SDD 20](20-catalogo-publicable-y-completa.md). **Esto es lo
7otro**: lo que hace el humano, en orden, con el comando al lado y el motivo debajo. Un comando por
8vez — nada de bloques largos para pegar a ciegas.
9
10**Convención**: `$` = lo tecleás vos. Si un paso puede hacerlo el agente solo, dice **[agente]** y
11sólo tenés que pedirlo.
12
13---
14
15# ETAPA 0 — La rutina, siempre
16
17Esto no es una etapa con final: es lo que se hace cada vez que se enciende la máquina. Si algo de
18acá falla, todo lo demás corre sobre arena.
19
20### 0.1 Después de CADA reinicio: dos comprobaciones
21
22```
23$ git -C ~/hammer fsck
24```
25Un crash puede dejar el `.git` corrupto. Si esto grita, **parar y avisar antes de seguir trabajando**:
26un commit encima de un repo roto empeora el problema.
27
28```
29$ pgrep -x crond
30```
31Si no imprime un número, **el latido está muerto y no se nota**: la cosecha del worker, la siembra de
32recetas y la regeneración del grafo dejan de correr en silencio. arje-zero como PID 1 no arranca
33cronie, así que pasa en cada arranque. Se revive con:
34
35```
36$ sudo /usr/bin/crond -s
37```
38Tiene que ser esa ruta y ese flag. **`rc-service` FALLA** — ya se probó.
39
40### 0.2 El disco, una vez al día
41
42```
43$ df -h /home
44```
45Por debajo de **50 G libres**, actuar. La válvula es:
46
47```
48$ cd ~/hammer && ./scripts/store-gc.sh --aplicar
49```
50⚠️ **En PRIMER PLANO, mirando la pantalla.** No en segundo plano, no con `&`, no con `nohup`. El
512026-08-07 este script informó «364 artefactos borrados, 24G liberados» **sin haber borrado ninguno**
52— corriendo en segundo plano el borrado no se materializaba y el `echo` se creía el `rm`. Ahora lleva
53un guardián que recuenta sobre el disco y sale con error si sobrevivió algo, pero la regla de correrlo
54en primer plano sigue en pie.
55
56Recupera ~24 G por ciclo de trabajo (los artefactos *superados*). Si hace falta más, el orden de
57reservas, de barata a cara, está en la nota `capacidad-disco-proyeccion`.
58
59### 0.3 El respaldo
60
61```
62$ cd ~/hammer && ./scripts/respaldo-storagebox.sh
63```
64**Es interrumpible y continuable**: podés cortarlo con Ctrl-C o apagar el laptop cuando quieras, y al
65relanzarlo sigue donde quedó — incluso a mitad de un fichero grande. Corré esto siempre que vayas a
66tener la máquina encendida un rato largo.
67
68Dato medido en la oficina el 2026-08-07: el uplink da **8 Mbps de subida, iguales por cable y por
69wifi** ⇒ el cuello está en la conexión del local, no en tu laptop, y **enchufar el cable no cambia
70nada**. Los 128 G del store no caben en una sentada; por eso el script sube primero el *cerebro*
71(estado + repo, que es lo que no se puede perder) y después el store.
72
73### 0.4 El worker
74
75```
76$ hcloud server list
77```
78Si `hworker-1` aparece, está facturando. Se apaga solo: lleva un *dead-man* propio que lo **borra**
79(no lo apaga — apagado seguiría facturando) tras 1 hora sin builds. Para ver si está trabajando de
80verdad **mirá los procesos, no la carga**: durante el `sleep 180` del bucle la carga marca 0 y parece
81idle sin estarlo.
82
83---
84
85# ETAPA 1 — De hoy a «la distro está PUBLICABLE»
86
87El orden está elegido para que lo bloqueante vaya primero y lo caro después. **La trampa clásica es
88invertirlo**: pasarse meses con el navegador y descubrir el día del anuncio que no se puede publicar.
89
90### Paso 1 — Destrabar las 12 recetas en deuda
91**[agente]** Es un solo agujero visto desde cuatro grafos: la cadena GUI de la cascada de mesa. No se
92pueden construir en el laptop (zig-skew rompe cairo) y fallan en el worker porque su rootfs no trae
93python3 ni cmake.
94
95El arreglo correcto es **declarar las herramientas en `[deps]` de cada receta, NO engordar el rootfs
96del worker**. Engordarlo parece más rápido y es justo lo que rompe la reproducibilidad: el build
97pasaría a depender de qué hay instalado en una máquina concreta.
98
99Vos: pedirlo, y tener el worker arriba.
100
101### Paso 2 — Terminar las licencias
102**[agente]** Quedan 913 de 1141, casi todas CLIs Go/Rust. Se automatiza con evidencia real y sin red:
103`Cargo.toml` trae el campo `license` y los módulos Go traen su `LICENSE` en el árbol.
104
105Para ver dónde estamos en cualquier momento:
106```
107$ cd ~/hammer && ./scripts/licencias.sh
108```
109
110**Lo que te toca decidir a vos**: cuando una licencia sea ambigua, se deja vacía. No se rellena a
111ojo. Un hueco contado es deuda; un hueco rellenado a ojo es una mentira sobre la que alguien va a
112construir.
113
114### Paso 3 — El texto de la licencia dentro del paquete
115**[agente]** Va en `takana pack`, **no** en la fase `install` de las recetas. Las fases entran al
116`ArtifactHash`, así que hacerlo ahí re-hashearía las 1141; pack es aguas abajo y sale gratis.
117
118### Paso 4 — El espejo de fuentes
119**[agente]** construye; **vos** decidís dónde vive y pagás el alojamiento.
120
121Es la obligación de la GPL que más se malinterpreta: no es «que el código exista en internet», es que
122quien recibe el binario pueda obtener **de nosotros** la fuente correspondiente. Como cada receta
123pinea `tarball` + `sha256`, es mecánico y encima verificable. **Tiene que existir antes de la primera
124descarga pública.**
125
126Decisión tuya: el Storage Box ya tiene 1 TiB y sobra sitio — puede servir de espejo de fuentes sin
127gastar un euro más, pero no está pensado para servir tráfico web. Conviene decidirlo antes.
128
129### Paso 5 — Las claves de firma 🔑 **esto es tuyo, no delegable**
130Hoy hay firma de índice; falta el nivel de arriba. Hace falta:
131
1321. Generar una **clave raíz fuera de línea** — en una máquina que no esté en internet, y que **nunca**
133   toque este laptop ni el worker.
1342. Guardar el respaldo de esa clave **en papel o en un medio que no esté conectado**, en otro sitio
135   físico.
1363. Generar claves de firma intermedias, rotables, firmadas por la raíz.
1374. Escribir el procedimiento de qué hacer si se filtra una.
138
139**Por qué te toca a vos**: una clave raíz que un agente puede leer no es una clave raíz. Y firma sin
140gestión de claves es teatro — peor que no firmar, porque da confianza falsa.
141
142### Paso 6 — La imagen en metal
143Falta **re-quemar el USB** (está a medias).
144
145```
146$ lsblk -o NAME,SIZE,TRAN,MODEL
147```
148⚠️ **Identificá el disco por tamaño/modelo/transporte, NUNCA por nombre.** Los nombres bailan entre
149arranques. Y **jamás quemar a un NVMe**: ahí vive tu sistema.
150
151Al validar imágenes de escritorio, **con pantalla, nunca sólo `-nographic`**. Dos trampas ya pagadas
152caro: `/dev/console` es el serial, así que cada capa tiene que escribir a `/dev/tty0` para que la
153veas; y para COSMIC en QEMU `-vga none` es **obligatorio** (virtio-gpu suma una VGA ⇒ dos salidas, y
154el panel se ancla en la que no estás capturando), con `-smp 8` porque el panel tiene deadline de
155arranque.
156
157### Paso 7 — Probar la actualización de verdad
158**[agente]** monta el ensayo; **vos** mirás el resultado. Instalar N, actualizar a N+1, que arranque.
159Y **rollback**, que con un store direccionado por contenido debería ser barato — es la ventaja
160natural de esta arquitectura, y conviene que sea función de primera clase antes de publicar, no
161después.
162
163### Paso 8 — `cups` y `bluez`
164**[agente]**. Impresión y bluetooth. Sin esto la distro se siente incompleta aunque todo lo demás ande.
165
166### Paso 9 — La infraestructura pública
167- Espejo de paquetes: **~30 G** separando los `-debug` en paquetes aparte (el 79% del store es
168  información de depuración). **Vos**: contratar el alojamiento.
169- Sitio de descarga con sumas y firmas, y las instrucciones para verificarlas.
170- **Publicar la evidencia de reproducibilidad**: los `ArtifactHash` de la clausura de cada imagen.
171  Esto es *el* diferenciador — es lo que convierte «somos reproducibles» en algo que un extraño puede
172  comprobar. No lo dejes para después: es lo único que nadie más está ofreciendo.
173- Un canal de reportes y una dirección para avisos de seguridad.
174
175### Paso 10 — Antes de anunciar: el ensayo general
176Ensayar el ciclo completo de seguridad **con un CVE de mentira**: detectar, construir, firmar,
177publicar, y que le llegue a una máquina instalada. Si esto no está ensayado, el primer CVE real te
178encuentra improvisando.
179
180---
181
182# ETAPA 2 — De PUBLICABLE a «la distro está COMPLETA»
183
184Acá ya estás publicado y tenés usuarios. Cambia el modo de trabajo: **cada cosa que agregues tiene
185que llegarles por el canal de actualización**, así que la Etapa 1 §7 tiene que estar sólida.
186
187### Paso 1 — Los WMs Wayland ligeros (empezá por acá)
188Es la mejor relación esfuerzo/resultado que queda: no hay una torre de C debajo. En orden:
189
1901. **`wlroots`** — la base de la que cuelgan casi todos. Sin esto no hay nada más.
1912. Los compositores: **`sway`**, `labwc`, `river`, `niri`.
1923. Los accesorios, **sin los cuales un WM no se usa de verdad**: `waybar`, `fuzzel`/`wofi`, `swaybg`,
193   `swayidle`, `swaylock`, `grim`, `slurp`, `wl-clipboard`.
194
195Hoy de toda esa familia sólo existen `foot` y `mako`.
196
197### Paso 2 — Las aplicaciones baratas, que son las que más se notan
198`imv` (imágenes), `zathura` (PDF), `mpv` (vídeo), un gestor de archivos, un editor gráfico. Cada una
199es una tarde, y juntas cambian por completo la sensación de la distro. **Medido: hoy no hay ninguna
200aplicación gráfica de terceros.**
201
202### Paso 3 — La deuda de fondo, antes de crecer más
203- Las **16 recetas con `compiler = "gcc"`**. Las 12 de Rust son un solo problema: falta el unwinder
204  de libgcc.
205- El **no-determinismo de 92 paquetes** (rutas `/src` en secciones `.debug_*`). El arreglo global
206  re-hashea ~720 recetas ⇒ **es una decisión tuya de arquitectura**, y conviene tomarla cuando el
207  corpus sea lo más chico posible. Cada mes que pasa es más caro.
208- **ADR 0012, la carrera del árbol de fuentes**: pendiente y sin decidir. Aviso registrado: *un lock
209  sólo en la extracción parece correcto y NO lo es.*
210
211### Paso 4 — LibreOffice
212Caro pero acotado. Antes que el navegador.
213
214### Paso 5 — El navegador 🏔️
215**Presupuestalo como un frente propio, no como una receta.** Firefox es Rust + C++ + su propio
216sistema de build, y arrastra cbindgen, nasm, nodejs y una cadena de `*-sys` con C++ — que es justo la
217frontera que el techo MSRV del sandbox (1.96) no cruza todavía. O sea que **antes de Firefox hay que
218subir el techo del sandbox**; empezar por la receta es empezar por el final.
219
220**Decisión tuya y de las primeras**: marca. Redistribuir Firefox con su nombre y logo exige cumplir
221la política de Mozilla (por eso Debian tuvo Iceweasel). Cumplir o rebrandear — pero decidido antes de
222construir, no después.
223
224---
225
226# ETAPA 3 — Después de COMPLETA: que siga viva
227
228La distro deja de ser un proyecto de construcción y pasa a ser uno de **mantenimiento**. Lo que hay
229que sostener:
230
2311. **Cadencia de release** escrita y cumplida. Una distro sin ritmo previsible pierde usuarios aunque
232   sea técnicamente mejor.
2332. **Seguridad continua**: seguir CVEs de lo empaquetado y publicar actualizaciones. Esto no se
234   pausa. Es el compromiso real que asumís al publicar.
2353. **La reconstrucción desde cero, cronometrada, en una máquina limpia.** Repetirla periódicamente:
236   es la prueba de que el proyecto no depende de este laptop — que es exactamente la preocupación que
237   originó el respaldo del 2026-08-07. Si un día deja de funcionar, te enterás por el ensayo y no por
238   una desgracia.
2394. **El reconstructor independiente**: otra máquina, idealmente de otra persona, que reconstruya y
240   compare hashes en continuo. Es el objetivo final del invariante de takana — el día que un tercero
241   confirme bit a bit lo que publicamos, la promesa deja de ser nuestra palabra.
2425. **Contribuciones de fuera**: si llega gente, hace falta cómo aceptar recetas sin bajar el listón
243   (revisión, firma, y que el aporte no rompa la reproducibilidad).
244
245---
246
247## Lo que yo haría el lunes que viene
248
249En este orden, y sin saltarse:
250
2511. `pgrep -x crond` y revivirlo. Sin latido no hay cosecha.
2522. Dejar corriendo el respaldo mientras trabajás.
2533. Pedir el arreglo del rootfs del worker → caen las 12 recetas en deuda.
2544. Pedir la automatización de las 913 licencias.
2555. **Generar la clave raíz fuera de línea.** Es lo único de la lista que no puede hacer nadie más que
256   vos, y es el que más tarda en poder empezarse si se posterga.