1# Runbook — COSMIC, el cuarto escritorio
2
3Estado al 2026-08-03: **COSMIC COMPONE EN QEMU Y UN CLIENTE PINTA.** `cosmic-comp` arranca sobre el
4kernel de hammer con arje-zero como PID1, toma el DRM, expone `wayland-1` y presenta frames; y
5`cosmic-bg` se conecta, entrega su buffer y el fondo aparece **con el color exacto que se le
6configuró** — `(0.13,0.29,0.53)` → `(33,74,135)`. O sea que la cadena cliente→compositor→KMS funciona
7de punta a punta. Este documento se escribe mientras se hace, no después.
8
9![cosmic-bg pintando en QEMU](../evidencia/cosmic-bg-qemu-2026-08-03.png)
10
11Que el color sea **el que se pidió** y no uno cualquiera es lo que hace de esto una medición y no una
12impresión: descarta que se esté viendo un buffer sin inicializar o el borrado del compositor.
13
14El paso anterior —el compositor solo, gris `(39,41,42)` y el cursor, 134 colores— quedó en
15[`cosmic-comp-qemu-2026-08-03.png`](../evidencia/cosmic-comp-qemu-2026-08-03.png), porque la
16diferencia entre las dos imágenes es exactamente la pregunta que el modo `bare` separa.
17
18COSMIC es el escritorio de System76, en Rust sobre **smithay** (compositor) e **iced/libcosmic**
19(clientes). Es el cuarto de hammer, tras [mirada](mirada-usb-nvidia.md),
20[KDE Plasma 6](kde-qemu-desktop.md) y [GNOME](gnome-qemu-desktop.md).
21
22## Por qué NO se parece a los dos anteriores
23
24KDE y GNOME costaron lo que costaron por la misma razón: una torre de C con Qt o
25glib/GObject/introspección debajo, donde cada capa se paga entera antes de ver un píxel. COSMIC no
26tiene esa torre. La primera receta —`cosmic-session`— salió **a la primera y sin una sola dep en C**:
27ELF estático, cero `NEEDED`.
28
29Lo que sí hereda es lo que ya está pago:
30
31| lo que COSMIC necesita | de dónde sale | costo |
32|---|---|---|
33| las deps en C de smithay (drm, gbm, seat, input, udev, xkb, pixman) | `mirada-compositor`, que ya es un compositor smithay de este lab | **cero** — misma lista |
34| `libdisplay-info` + `hwdata` | copiadas byte a byte de la cola GNOME | **cero** — mismo hash, artefacto ya sellado |
35| `bash`, `dbus-run-session`, `hicolor-icon-theme`, mesa-llvmpipe | corpus | cero |
36| el andamiaje de arranque en QEMU (`run-qemu-desktop.sh`, base rootfs, console-getty, screendump) | campañas KDE/GNOME | cero |
37
38La deuda propia que sí trae, y que ninguna de las otras campañas tocó, es la del **unwinder de la std
39de rustc** cuando el enlace no es estático — la misma que ya está documentada para las recetas Cargo
40del corpus.
41
42## El pin es de la SUITE, no de cada paquete
43
44COSMIC versiona **todos** sus repos en lockstep con el tag `epoch-N`. Comprobado repo por repo: los
45doce componentes están en `epoch-1.5.0`.
46
47**No mezclar epochs entre piezas.** Comparten protocolos propios (`cosmic-protocols`) y el formato de
48configuración (`cosmic-config`); un desajuste ahí no da error de compilación, da un escritorio que
49arranca y no se entiende consigo mismo — que es mucho más caro de diagnosticar.
50
51## La cola
52
53`recipes/incoming-cosmic/`, aislada (otro agente comparte el repo; nunca `git add -A`).
54
55Las deps se resuelven **hermano → padre**: desde `incoming-cosmic/` se ven las recetas de
56`recipes/`, pero **no** las de `incoming-gnome/` ni `incoming-kde/`. Por eso `libdisplay-info` y
57`hwdata` entran copiadas.
58
59**Copiar es gratis sólo si TODA la clausura transitiva resuelve a lo mismo.** El ArtifactHash no
60depende de la ruta de la receta, así que un fichero idéntico *cuyas deps resuelven igual* da el mismo
61hash ⇒ cache hit sobre el artefacto que ya existe. Se cumplió con `libdisplay-info`, `hwdata` y
62`nasm`, y se verificó con `hammer hash` **antes** de copiar (`b3:260f0519`, `b3:bdc36cf9`,
63`b3:33383070`), no después. Dónde deja de cumplirse —y por qué importa— está en la sección de
64`cosmic-settings-daemon`, más abajo.
65
66## Qué levanta la sesión, y por lo tanto el orden de ataque
67
68`cosmic-session/src/main.rs` es la lista autoritativa —el mismo método que cerró la capa JS de GNOME:
69*leé el fichero donde el programa declara lo que arranca, no lo descubras de a uno*:
70
71```
72cosmic-comp  →  cosmic-notifications · cosmic-panel · cosmic-app-library
73             →  cosmic-launcher · cosmic-workspaces · cosmic-osd · cosmic-bg · cosmic-idle
74```
75
76Más `cosmic-settings-daemon` y `xdg-desktop-portal-cosmic` fuera de esa lista.
77
78| pieza | estado | hash |
79|---|---|---|
80| `cosmic-session` | ✅ sellado | `b3:81f02351` |
81| `cosmic-icons` | ✅ sellado (671 SVGs) | `b3:94d06f77` |
82| `dav1d` 1.5.4 | ✅ sellado (dep arrastrada, ver gotcha 8) | `b3:aab7a874` |
83| **`cosmic-comp`** | ✅ **SELLADO — el gate** | `b3:b8abc52f` |
84| `cosmic-bg` (dinámico, PINTA) | ✅ sellado | `b3:b2cfc410` |
85| `cosmic-idle` (dinámico) | ✅ sellado | `b3:e1806acc` |
86| `pulseaudio` · `pipewire` (cadena del settings-daemon) | ✅ sellados | `b3:e1ff4736` · `b3:338d1d8c` |
87| `cosmic-osd` · `cosmic-panel` · `cosmic-settings-daemon` | 🔨 en construcción | — |
88| `cosmic-launcher` · `cosmic-app-library` · `cosmic-workspaces-epoch` · `cosmic-notifications` | receta escrita, sin construir | — |
89
90**El orden no es el de la lista de arranque.** `cosmic-bg` va antes que el panel a propósito: habla
91Wayland con `smithay-client-toolkit` y **no toca libcosmic ni iced**, mientras que panel, launcher,
92osd y workspaces son todos clientes de iced. Con el fondo sellado, «pinta el fondo pero no el panel»
93separa la capa de UI del transporte; sin él, las dos preguntas llegan juntas.
94
95### `cosmic-settings-daemon`: por qué queda al final y NO se resuelve copiando
96
97Es el único con cadena propia. Su workspace incluye `audio-server` como dep de path **no opcional**,
98que arrastra `cosmic-pipewire` → `pipewire-sys` → `libpipewire-0.3` por pkg-config. Y `pipewire` hoy
99vive sólo en las colas GNOME y KDE.
100
101**Acá el truco de copiar deja de ser gratis, y eso corrige lo que dice más arriba.** La regla completa
102es: *copiar una receta entre colas es gratis sólo si **toda su clausura transitiva** resuelve a lo
103mismo.* Se cumplió con `libdisplay-info`, `hwdata` y `nasm` —sus deps están todas en el corpus—, y
104**no** se cumple con pipewire: de sus catorce deps, cinco viven sólo en colas ajenas
105(`dbus-shared`, `alsa-lib`, `libsndfile`, `pulseaudio`, `zlib-shared`) y —lo decisivo— **`glib`
106resolvería distinto**. Desde `incoming-gnome`, `glib` es la sombra de esa cola (`b3:f6ccdf98`); desde
107`incoming-cosmic` sería la del corpus (`b3:93d2cad0`). Son recetas distintas, no la misma en dos
108lugares.
109
110O sea que copiar produciría un **segundo pipewire** construido contra otra glib, arrastrando su cadena
111entera. Y eso no es sólo caro: es exactamente el cuadro que la campaña GNOME ya midió y evitó —dos
112glib distintas con 370 rutas solapadas y dos registros de GType en un proceso—.
113
114Antes de tocar nada se midió con `yupana radio` (la puerta única, nunca `grep`): `pipewire` tiene
115radio 1 en GNOME y 2 en KDE, pero `glib` del corpus tiene **21 dependientes transitivos y afecta la
116imagen escritorio-gnome**.
117
118**Y después se midió el costo real, que resultó mucho menor que la estimación.** Copiar pipewire a
119`incoming-cosmic` necesita **cuatro** recetas hermanas —`alsa-lib`, `dbus-shared`, `libsndfile`,
120`pulseaudio`—, no las seis contadas a ojo, y **tres de ellas dan hash idéntico y ya están selladas**.
121Sólo `pulseaudio` y `pipewire` hay que construir.
122
123Eso refina la advertencia de arriba en el punto que importa: **el peligro de las dos glib es
124mezclarlas en UNA IMAGEN**, y la imagen COSMIC tiene una sola. Acá el costo es de builds, no de
125corrección. Lo que sigue vigente es no promover a ciegas entre colas.
126
127Gotcha del copiado, que cuesta un minuto de confusión: `[source] patches` se resuelve **relativo a la
128receta**, así que copiar el `.toml` sin su `.patch` da «no pude leer patch» y el hash ni siquiera se
129calcula.
130
131## 🚪 EL GATE PASADO: cosmic-comp compila (2026-08-03)
132
133`b3:b8abc52f`, 51 min 39 s de cargo con `CARGO_BUILD_JOBS=1` y `lto = "fat"`. **A la primera**, salvo
134el `--bin` del gotcha 1. Sin un solo parche a la fuente.
135
136Lo que dice el enlace es la parte que vale, porque es la medición y no la impresión:
137
138```
139NEEDED: libdisplay-info.so.2 · libgbm.so.1 · libseat.so.1 · libudev.so.1
140        libinput.so.10 · libpixman-1.so.0 · libxkbcommon.so.0 · libc.so
141```
142
143Ocho, y las siete primeras son **exactamente** los backends de smithay que la receta declara. La
144octava es musl. **No hay `libgcc_s`** — o sea que el compositor no arrastra la deuda del unwinder que
145sí tienen varias recetas Cargo del corpus, porque acá el enlace es dinámico contra musl y no hay
146`+crt-static` que forzar. Y **no aparece nada que no se haya declarado**: la clausura de build y la de
147runtime coinciden, que es la propiedad que uno quiere y casi nunca se cumple gratis.
148
149Que un compositor Wayland completo —DRM, GBM, EGL, libinput, seat, Vulkan, XWayland, un renderer
150multi-GPU y una capa de UI en iced— cierre con ocho librerías compartidas y ningún parche es el
151resultado más limpio de las cuatro campañas de escritorio.
152
153## 🖥 EL PRIMER ARRANQUE: qué falló y qué no (2026-08-03)
154
155Tres imágenes y tres causas distintas, todas medidas. Vale dejarlas porque **ninguna estaba en el
156camino que uno anticipa**, y las tres se manifestaron a varias capas de distancia de su causa.
157
158**1. `cosmic-session` no es opcional en el sentido que yo asumí — y `cosmic-settings-daemon` tampoco.**
159El compositor arrancó perfecto y le devolvió a la sesión su `WAYLAND_DISPLAY=wayland-1`; el gestor
160entonces intentó lanzar `cosmic-settings-daemon`, no lo encontró, y **panickeó**:
161
162```
163INFO  cosmic_session: got environmental variables from cosmic-comp: [("WAYLAND_DISPLAY", "wayland-1")]
164ERROR panic: 'failed to start settings daemon: NotFound' src/main.rs:255
165```
166
167Es un `.expect()`, sin feature que lo apague. **Y NO es el único — son TRES**, y esto corrige lo que
168esta misma sección afirmaba hace unas horas:
169
170| línea | componente | qué pasa si falta |
171|---|---|---|
172| `main.rs:255` | `cosmic-settings-daemon` | panic |
173| `main.rs:306` | `cosmic-notifications` | panic |
174| `main.rs:325` | `cosmic-panel` | panic |
175
176El resto (app-library, launcher, workspaces, osd, bg, idle) va por `start_component()`, que ante un
177fallo sólo hace `error!("failed to start …")` y sigue (`main.rs:558`). O sea que **el mínimo viable de
178una sesión COSMIC son cuatro binarios**: compositor + esos tres.
179
180**Cómo se equivocó el diagnóstico, que es la parte reusable**: leí `start_component()`, vi que sólo
181logueaba, y generalicé a «todos menos el settings-daemon». Pero notifications y panel **no pasan por
182esa función** — tienen su propio `.expect()` unas líneas antes. Buscar la función que lanza no es lo
183mismo que buscar los `\.expect(` del fichero; **grepear la construcción que mata cuesta lo mismo y no
184generaliza de más**. **Esto corrige lo que decía la sección de
185cosmic-settings-daemon**: no es que sin él se pierdan el brillo y el tema, es que **no hay sesión**.
186Queda por eso el modo `bare` en `cosmic-start` —el camino que upstream ya soporta como
187`install-bare-session`—: se lanza el compositor solo y los clientes a mano contra su WAYLAND_DISPLAY.
188Separa «¿compone?» de «¿arranca la sesión?», que son dos preguntas y estaban viniendo juntas.
189
190**2. La pantalla negra era `libz.so.1`.** El corpus trae `zlib` estática, que le alcanza a todo el
191cierre de COSMIC. Pero `kms_swrast_dri.so` es un `.so` que mesa abre con `dlopen` y NEEDea
192`libz.so.1`:
193
194```
195MESA-LOADER: failed to open kms_swrast: Error loading shared library libz.so.1
196WARN  cosmic_comp::backend::kms: Failed to add device /dev/dri/card0: Failed to initialize GBM device
197```
198
199Sin driver de software no hay GBM, y **el compositor arranca igual y presenta una pantalla negra**. La
200causa está a tres capas del síntoma. Se arregla agregando `zlib-shared` como raíz del hidratador.
201
202**3. Los clientes NO pueden ser estáticos.** `cosmic-bg` moría con «The wayland library could not be
203loaded» **teniendo `libwayland-client.so.0` en el rootfs**. `wayland-client` entra con la feature
204`dlopen`: carga libwayland en runtime en vez de enlazarla, y **un binario musl estático no tiene
205dlopen funcional**. No faltaba la librería: faltaba poder abrirla. Todos los clientes pasan a
206`link = "dynamic"`.
207
208**Lo que NO falló, y conviene decirlo:** el compositor no necesitó un solo parche, ni una perilla de
209KMS, ni forzar modeset legacy. Las cuatro perillas de render por software heredadas de KDE y GNOME
210(`GBM_ALWAYS_SOFTWARE`, `kms_swrast`, `LP_NUM_THREADS=1`) alcanzaron. GNOME costó cinco muros para
211llegar a este punto; COSMIC costó tres, y ninguno era del compositor.
212
213### Dos carreras con /run, la misma causa
214
215`dbus-daemon --system` falló con «Failed to bind socket /run/dbus/system_bus_socket: No such file or
216directory» **aunque el directorio se creaba al principio del script**, y dbus-run-session se quejó
217por su lado de que `XDG_RUNTIME_DIR` no existía. Entre el arranque del getty y el uso pasan varios
218segundos en los que arje-zero sigue montando, y un tmpfs sobre `/run` se lleva puesto lo que hubiera.
219**Crear justo antes de usar** es la única forma de no depender de ese orden; comprobar al principio y
220usar al final es exactamente cómo se cuela una carrera — la misma forma del bug de PolicyKit1 que se
221cerró hoy en GNOME.
222
223## Gotchas medidos (no previstos)
224
2251. **`cargo rustc --` exige UN target.** La fase compile del lab pasa flags tras el `--`, y cualquier
226   paquete con binario + lib + ejemplos corta con «extra arguments to `rustc` can only be passed to
227   one target». Se arregla con `flags = ["--bin", "<nombre>"]`. Le pasa a cosmic-comp y a cosmic-bg
228   (workspace con `config/`), y le va a pasar a casi todos: **ponelo desde el principio.**
2292. **`start-cosmic` es bash de verdad, no sh.** Usa `mapfile`, `[[ ]]` y expansión indirecta
230   `${!var}`; con el busybox del rootfs no arranca. `bash` ya está en el corpus, pero **tiene que
231   entrar en la imagen** — y no lo pide ningún `[deps]`, así que no lo va a traer nadie por accidente.
232   Lo mismo con `dbus-run-session` (de `dbus`), que es lo que el script exec-uta al final.
2333. **`rust-toolchain.toml` con `channel = "1.93"` es inerte acá** — es una perilla de rustup, y el
234   sandbox tiene el rustc de Alpine (1.96) pelado. Conviene saberlo antes de «arreglarlo».
2354. **`cosmic.desktop` existe DOS veces** (en cosmic-session y en cosmic-comp) con contenido distinto
236   y en la misma ruta. El de cosmic-comp es el de la «bare session» y apunta a `/usr/bin/cosmic-service`,
237   que vive en la rama de systemd que acá no va. Se instala **sólo** el de cosmic-session; si entraran
238   los dos, quién gana depende del orden de hidratación y el que pierde es el bueno.
2395. **`libsystemd` no es systemd.** La feature `default = ["systemd"]` de cosmic-comp trae el crate
240   `libsystemd`, que es una **reimplementación en Rust** del protocolo, no un binding a la C. Y
241   `logind` habla `org.freedesktop.login1`, que acá lo sirve `arje-logind-compat`. No hay que apagar
242   nada: el nombre de la feature es el del protocolo, no el del programa que lo contesta.
2436. **Las features de smithay que asustan no cuestan deps de build**: `backend_vulkan` (crate `ash`),
244   `backend_x11` (`x11rb` con `dl-libxcb`) y `xwayland` cargan todo por **dlopen**. Son deuda de
245   RUNTIME —libxcb y vulkan-loader viven hoy sólo en la cola KDE—, no un muro de compilación.
2467. **Todo cliente de la suite lleva las MISMAS CUATRO deps: `libxkbcommon`, `pkgconf`,
247   `libudev-zero`, `libinput`** — incluso las piezas sin interfaz. Las tres primeras se descubrieron
248   de a una, un build por dep, hasta que la línea de enlace las mostró juntas:
249
250   ```
251   -Wl,-Bstatic  -ludev  -linput  -lxkbcommon …
252   ```
253
254   **El error dice la que falta primero; el COMANDO dice todas.** Leerlo entero la primera vez habría
255   ahorrado tres builds. Los tres llegan por la cadena de libcosmic —enumeración de monitores y de
256   dispositivos de entrada—, no por nada que el cliente haga a la vista.
257
258   Y el camino hasta ahí fue de razonamientos buenos y falsos, que es lo que vale dejar escrito:
259   - `cosmic-bg` fue sin `[deps]` porque «habla el protocolo en Rust y no toca C». Reventó en el
260     `build.rs` de `smithay-client-toolkit` pidiendo `xkbcommon.pc`: **sctk ENLAZA libxkbcommon**; el
261     que la dlopea es `winit`, que es otra capa. Hablar Wayland en Rust dice cómo viaja el byte, no
262     con qué se interpreta un teclado.
263   - `cosmic-idle` fue sin `[deps]` porque *ese* argumento ya no aplicaba —no usa sctk— y un demonio
264     de inactividad no interpreta teclas. Reventó en el ENLACE con `-lxkbcommon`, arrastrado por
265     **`cosmic-settings-config`**: de ahí sale la tabla de atajos y la usa **todo** componente de la
266     suite. La dep no viene de lo que el paquete hace, sino de la librería de configuración común.
267
268   La lección de método vale más que la dep: **la dep no se deduce de la función del paquete.** Está
269   escrita en el `build.rs` que panickea o en la línea de enlace, y las dos veces el error dijo
270   exactamente quién y por qué. El `link = "static"` sobrevive porque el artefacto de libxkbcommon
271   trae `.a` además de `.so`.
2728. **Una feature apagada en el paquete puede estar prendida por otro.** `cosmic-bg` declara `image`
273   con `default-features = false` y sin AVIF, y aun así compila `dav1d-sys`: **las features de cargo
274   se UNIFICAN en el grafo**. Se resolvió trayendo `dav1d` (b3:aab7a874) en vez de parchear el
275   Cargo.toml de upstream — si el grafo dice que sabe decodificar AVIF, que lo sepa de verdad.
276   Mismo modo de falla que un `.pc Requires` arrastrando una dep que nadie declaró.
277
2789. **`cosmic-wallpapers` no se puede empaquetar del tarball: está en git-lfs.** El default de
279   cosmic-bg apunta a `/usr/share/backgrounds/cosmic/orion_nebula_nasa_heic0601a.jpg`, y el archivo
280   de GitHub de ese repo pesa **20 KB** — son punteros LFS, no imágenes. Una receta escrita del modo
281   normal produciría un paquete de ficheros de texto que además *parecería* correcto: se instalarían
282   con el nombre bueno en la ruta buena. Mientras tanto `cosmic-start` escribe la config de USUARIO
283   con una fuente `Color`, que cosmic-bg soporta de fábrica — y va en el lanzador, no en el artefacto,
284   porque es política de la imagen de prueba y no algo que el paquete prometa.
285
286## Cómo se construye
287
288```sh
289cd ~/hammer
290./target/release/hammer --store store hash recipes/incoming-cosmic/<pieza>.toml   # dry-run, ~2ms
291./target/release/hammer build recipes/incoming-cosmic/<pieza>.toml --store store
292```
293
294## Lo que falta, en orden
295
2961. Cerrar `cosmic-comp`. Es el gate: sin compositor no hay escritorio que probar.
2972. El primer cliente de iced (`cosmic-panel`), que es la pregunta abierta de verdad — libcosmic con
298   `winit`/`wgpu` puede pedir más de lo que pide cosmic-bg.
2993. `cosmic-settings-daemon`, `cosmic-launcher`, `cosmic-app-library`, `cosmic-notifications`,
300   `cosmic-osd`, `cosmic-workspaces-epoch`, `cosmic-idle`.
3014. Imagen QEMU con `bash` + `dbus-run-session` + `hicolor-icon-theme`, y **validar CON PANTALLA**
302   (`DISP=gtk` + `screendump`, contar colores distintos) — regla heredada de KDE y GNOME.
3035. `xdg-desktop-portal-cosmic` y `cosmic-greeter`, que son de la etapa siguiente.