1# ADR 0015 — qorpa: el mundo glibc entra enjaulado, y no entra al store
2
3- **Estado:** PROPUESTO — nombre ADOPTADO (`qorpa`, 2026-09-03); implementación EN CURSO por el
4  §Orden de trabajo. Este documento decide la frontera; el código viene después.
5- **Fecha:** 2026-09-03
6- **Frontera (a crear):** `hammer qorpa {pull,create,run,export,list,prune}`,
7  `/var/lib/hammer/qorpa/images/<sha256>/`, `/var/lib/hammer/qorpa/instances/<id>/`,
8  `instance.toml` (manifiesto), clase de nodo `ajeno` en `build-state.py`.
9- **Superficie:** verbos en inglés, mensajes en castellano — `CLAUDE.md` regla 4. Este ADR nació
10  proponiendo `traer/crear/correr` y se corrigió el 2026-09-03; el nombre `qorpa` sí es quechua.
11- **Continúa:** [SDD 04](../04-overlay.md) (overlay), [SDD 16](../16-harkaq-jaula.md) (harkaq),
12  [ADR 0004](0004-no-custom-nix.md) (hammer no usa nix), [SDD 20](../20-catalogo-publicable-y-completa.md)
13  (catálogo publicable).
14- **Absorbe:** [`plan-jaula-juegos.md`](../plan-jaula-juegos.md) §Capa 3. Su **F1** pasa a ser un
15  caso particular de este ADR (imagen de tipo 2); su **F0** (flatpak al catálogo) queda innecesaria;
16  su **F2** (glibc + multilib 32-bit desde fuente, «una campaña entera») queda **cancelada**.
17
18---
19
20## Contexto
21
22### El problema, medido
23
24El corpus tiene hoy 788 recetas selladas y cuatro escritorios que cierran. De apps de usuario final
25tiene esto:
26
27```
28kate konsole dolphin okular gwenview ark spectacle kcalc filelight kfind · foot · vim
29```
30
31Ni navegador, ni suite ofimática, ni reproductor, ni editor de imagen. La pregunta natural es qué
32lo impide, y la respuesta se parte en tres montones **con causas distintas**:
33
34| montón | qué hay adentro | qué lo bloquea |
35|---|---|---|
36| **A** | Firefox, Chromium, LibreOffice, mpv, GIMP, Inkscape, Blender, OBS | **nada estructural**: son Wayland-nativos y compilables. Falta escribirlas. |
37| **B** | Steam/Proton, IDEs de JetBrains, Zoom/Slack/Discord/Spotify, binarios comerciales | **la libc**. Son prebuilts glibc. Mueren en el loader, antes de tocar el servidor gráfico. |
38| **C** | herramental X11: `xdotool`, `xbindkeys`, `x11vnc`, Barrier | **Wayland**, y Xwayland tampoco los salva (sólo ve clientes X). |
39
40La medición que ordena el debate: **la intersección de «sólo X11» con «compilable desde fuente en
41musl» es casi vacía**. Casi todo lo que se pierde por Wayland ya estaba perdido por musl. El montón
42que duele es **B**, y ninguna cantidad de trabajo en el corpus lo mueve: son binarios que nadie va a
43recompilar.
44
45### Por qué no alcanza con lo que ya decidimos
46
47Tres salidas parecen razonables y las tres son peores:
48
491. **Construir glibc + multilib 32-bit en el corpus.** Es la F2 del plan de juegos, descrita ahí
50   mismo como «una campaña entera»: toolchain dual, loader, locales. Y aun así no corrés Steam: el
51   cliente espera un userland glibc completo, no una libc suelta.
522. **Flatpak al catálogo** (F0 del mismo plan). Funciona, pero mete ostree + flatpak + su modelo de
53   runtimes y portales, y la cadena de custodia pasa a ser de flathub, no nuestra. Era la validación
54   barata mientras no hubiera jaula propia.
553. **Aflojar Wayland-only.** No resuelve B —el problema es la libc— y sí revierte una decisión
56   tomada con fundamento.
57
58### Lo que ya está construido
59
60Este ADR compone piezas existentes. No inventa infraestructura:
61
62| pieza | dónde | estado |
63|---|---|---|
64| aislamiento de namespaces | `recipes/bwrap.toml` | sellada; ya es dep del lab de build |
65| capa mutable sobre base inmutable | [SDD 04](../04-overlay.md) + `crates/hammer-overlay` | overlayfs, `hammer try` |
66| política de grano fino en el kernel | [SDD 16](../16-harkaq-jaula.md) | Landlock + seccomp; fase 1 ✅, barrido con 0 irreducibles |
67| rootfs ajeno pineado por sha256 | `scripts/lab-image.sh` | en producción desde 2026-08-10 |
68| `newuidmap` / `newgidmap` / `/etc/subuid` | `recipes/shadow.toml` | **instalados**; falta provisionarlos |
69| kernel con lo necesario | `recipes/linux-metal.toml:111-114` | `OVERLAY_FS` (+redirect_dir/index/xino/metacopy), `USER_NS`, `NAMESPACES`, `SECURITY_LANDLOCK`, `SECCOMP` |
70
71Nada de esto hay que re-sellar. El kernel propio ya arranca con todo encendido.
72
73---
74
75## Decisión
76
77**Se adopta un subsistema de imágenes ajenas: rootfs de otras distribuciones, traídos enteros y
78pineados por digest, que corren enjaulados sobre el mismo kernel y comparten con el escritorio
79únicamente protocolos y nodos de dispositivo. Sus artefactos NO entran al store.**
80
81### D1 — La invariante del store
82
83> **Una imagen ajena no es un artefacto y no vive en el store.**
84
85No es prolijidad. El store promete que **cada entrada se reconstruye desde fuente bit a bit**. Un
86rootfs de Fedora no. Meterlo ahí haría que el store mienta, y sería la misma clase de error que el
87artefacto vacío que ya nos costó caro: *algo que se lee como garantía y no lo es*
88(`CLAUDE.md` regla 3 — «un ausente falla ruidosamente; un vacío llega hasta el final diciendo que
89todo fue bien»).
90
91Espacio de nombres paralelo, direccionado por digest, **fuera de `hash_inputs` de todo**:
92
93```
94/var/lib/hammer/qorpa/images/<sha256>/    imagen  — INMUTABLE, verificada por digest
95/var/lib/hammer/qorpa/instances/<id>/
96    ├── instance.toml                     manifiesto — LA VERDAD
97    ├── upper/                            capa mutable — CACHÉ
98    └── work/                             overlayfs
99```
100
101El precedente exacto ya existe y funciona: `scripts/lab-image.sh` trae el rootfs del lab pineado por
102sha256 porque `apk add` contra Alpine edge es irrepetible por diseño. Misma figura, otro consumidor.
103
104### D2 — La regla del borde
105
106> **Se cruza el borde con protocolos y nodos de dispositivo, nunca con librerías compartidas.**
107
108| qué | cómo cruza | por qué |
109|---|---|---|
110| pantalla | socket `wayland-0` | protocolo, no ABI. La imagen trae su `libwayland`. |
111| audio | socket de PipeWire | ídem |
112| IPC | socket de D-Bus (opcional, por sesión) | ídem |
113| GPU | `/dev/dri/*` | ABI de kernel (DRM), estable |
114| juegos | `/dev/ntsync` | ABI de kernel |
115| input | `/dev/input/*` (sólo si se concede) | ABI de kernel |
116| **Mesa / libc / cualquier `.so`** | **no cruza** | nuestro Mesa es musl; un proceso glibc no lo carga. La imagen trae el suyo, que habla DRM con nuestro kernel sin conocerlo. |
117
118El corolario práctico: **la jaula no sabe ni le importa qué libc hay adentro.** Glibc, musl ajeno,
119uclibc, bionic. Lo único que cruza es la ABI del kernel, que es estable por contrato. Por eso este
120mecanismo resuelve el montón B completo de una sola vez.
121
122El error a evitar —y es el que convierte esto en un pantano— es intentar compartir librerías del
123host «para ahorrar espacio».
124
125### D3 — El manifiesto es la verdad; el `upper` es caché
126
127> **Una instancia se declara, no se acumula.**
128
129Si el `upper` con 200 paquetes instalados a mano fuese el activo, tendríamos un blob irreemplazable:
130justo lo que hammer existe para no tener. La relación correcta es la misma que receta↔artefacto:
131
132Los campos van en inglés como el resto de la superficie (`CLAUDE.md` regla 4):
133
134```toml
135# /var/lib/hammer/qorpa/instances/games/instance.toml
136base     = "sha256:…"                 # digest de la imagen, inmutable
137distro   = "arch"                     # informativo
138packages = ["steam", "mesa"]
139
140[grants]                              # POR DEFECTO NADA
141sockets = ["wayland", "pipewire"]
142devices = ["/dev/dri", "/dev/ntsync"]
143dirs    = [{ host = "~/Juegos", inside = "/home/user/Juegos", mode = "rw" }]
144network = true                        # lo necesita el gestor de paquetes y lo necesita Steam
145
146[export]                              # capa de transparencia; ver D5
147binaries = ["steam"]
148apps     = ["steam.desktop"]
149```
150
151Consecuencias que se caen solas:
152- **`hammer qorpa recreate <id>`** reconstruye la instancia desde el manifiesto. El `upper` es
153  descartable.
154- **Actualizar la base** (Fedora 43 → 44) no es un rebase riesgoso: se cambia el digest y se recrea.
155- **El respaldo** es el manifiesto (KB), no el `upper` (GB). `respaldo-storagebox.sh` no toca
156  `/var/lib/hammer/qorpa/instances/*/upper` y eso es correcto, no un olvido.
157- La poda tiene una regla trivial: **un `upper` siempre se puede borrar.**
158
159**✅ COMPLETADO 2026-09-03 — hasta acá `packages` era una lista que nadie leía.** Durante unas
160horas el ADR afirmaba las cuatro consecuencias de arriba mientras `recreate` confesaba en su propia
161salida que «instalarlos todavía es a mano»: o sea que el `upper` **sí** era el activo y el
162manifiesto un adorno. Ahora `hammer qorpa provision <id>` instala lo declarado, y **`recreate` lo
163llama solo** (`--no-provision` para no hacerlo).
164
165| decisión | por qué |
166|---|---|
167| el gestor se **detecta** (`apt`, `pacman`, `dnf`, `apk`), no se configura | cada imagen trae el suyo. Y **no se multiplexa**: el ADR rechaza un comando único al estilo `pmm` de Bedrock; acá se elige cuál correr, no se inventa una interfaz que los tape |
168| `provision` **ensancha la política y lo dice en la cara** | instalar pide las tres cosas que una instancia bien declarada no tiene —red, root y la imagen sin sellar—. Se ensancha sólo durante esa operación, el manifiesto **no se toca**, y el siguiente `run` vuelve a lo escrito. Ensancharlo en silencio sería exactamente lo que D7 prohíbe |
169| el registro (`provisioned.toml`) vive **fuera** del `upper` | si viviera dentro se iría con la capa y nadie sabría qué había. Por eso `recreate` lo borra a mano: un registro que afirma paquetes sobre una capa recién vaciada es la forma más pura del error de la regla 3 |
170| los nombres de paquete se **validan y se comillan** | salen del manifiesto, que lo escribe una persona; `strace; rm -rf /` no llega al guión |
171
172**Las dos manías que sólo aparecen provisionando de verdad** (medidas, no leídas): el bootstrap de
173Arch trae la **mirrorlist entera comentada** —`pacman` muere con «no servers configured»— y el
174**llavero sin inicializar**, con lo que toda firma es inválida; el guión pone el mirror geo oficial
175**avisando cuál**, y corre `pacman-key --init && --populate` sólo si falta. `apt`, en cambio, no
176necesita ni un workaround: es el dividendo del rango de subuid.
177
178**Probado de punta a punta en los dos gestores**: `apt` sobre Ubuntu base y `pacman` sobre el
179bootstrap de Arch instalan, el binario corre después con la red apagada otra vez, y un `recreate`
180tira la capa y la deja igual — que es la prueba de esta sección entera.
181
182### D4 — Granularidad: cuatro tipos, no uno
183
184| tipo | qué es | mutable | ¿sellable? | para qué |
185|---|---|---|---|---|
186| **1** | rootfs completo con gestor (Fedora+`dnf`, Arch+`pacman`) | sí | no | «literalmente lo que sea» |
187| **2** | runtime curado congelado (Steam Linux Runtime *sniper*, runtime freedesktop) | **no** | **sí**, `file_drop` por sha256 | cadena de custodia nuestra |
188| **3** | bundle por app (AppImage) | no | sí | una app suelta |
189| **4** | glibc en un prefijo, sin jaula | — | — | **rechazado**: frágil y ensucia justo lo que se protege |
190
191El tipo 2 es la F1 del plan de juegos y **sigue siendo el preferido cuando alcanza**: es inmutable,
192se sella y su digest entra en el índice firmado. El tipo 1 existe porque `dnf install` es
193precisamente lo que el tipo 2 no permite.
194
195### D5 — Transparencia: shims generados, no un sistema de ficheros
196
197El objetivo es el poder de Bedrock Linux —un espacio de nombres unificado, apps de cualquier
198«stratum» disponibles en todos lados— **sin sus formas**: un FUSE global en el camino de cada
199`exec`, integración a nivel de PID 1, y arbitraje por heurística de qué binario gana.
200
201Acá no hace falta nada de eso, porque **el FHS de esta distro ya es una proyección, no la verdad**:
202`hammer hydrate` proyecta artefactos del store a un árbol. Extender la proyección a instancias es
203idiomático. Tres capas:
204
205**Capa 1 — shims.** Al crear o actualizar una instancia se **generan** lanzadores finos en el
206espacio del host: un script que hace `exec` hacia adentro, más el `.desktop` con su icono. Firefox
207de Fedora aparece en el menú de Plasma al lado de kate; `steam` está en el `PATH`.
208
209Gana en tres cosas concretas contra el FUSE:
210- **cero costo en runtime** — no hay proceso en el camino crítico de cada `exec`;
211- **inspeccionable** — `cat` al shim y ves exactamente qué hace;
212- **revocable** — se borran los shims y la instancia desaparece del sistema sin desmontar nada.
213
214⚠ **Se generan, no se copian.** El `Exec=` de un `.desktop` ajeno es texto ajeno; copiarlo pondría
215una línea de comando que no escribimos en el menú del usuario.
216
217**Capa 2 — se exporta lo declarado.** Si se exporta todo, el `ls` y el `systemctl` de Fedora compiten
218con los nuestros. Ésa es la falla de Bedrock: **arbitra en tiempo de `exec`**, con heurísticas. Acá
219la lista `[export]` del manifiesto resuelve la ambigüedad **al declarar**. Tiene precedente directo:
220la hidratación del escritorio ya va por lista explícita (`TARGETS="…"`), nunca por glob.
221
222**Capa 3 — el grafo lo sabe.** Los nodos exportados entran en `build-state.json` con **clase
223`ajeno`**, y el reporte pasa a decir:
224
225```
226escritorio-kde       187/188 listo   falta   1  (raíces 14, + 1 ajenas)
227```
228
229Así sale hoy, de verdad: el `xwayland` que era `wanted` (deuda: receta por escribir) pasó a `ajeno`
230y **la deuda se disolvió sin escribir la receta**. Dos decisiones que sostienen la cifra:
231
232- **Los ajenos se restan del denominador.** Si entraran en la fracción, el número que todo el mundo
233  lee como «cuánto construimos» crecería solo cada vez que alguien enjaula una app ajena.
234- **La declaración vive en `docs/state/qorpa-ajenos.toml`, en el repo — no se lee de
235  `/var/lib/hammer`.** `build-state.json` se commitea y lo regenera el cron en dos máquinas: si la
236  clase saliera de las instancias instaladas, cada una diría algo distinto y se pisarían en cada
237  cosecha. Es el mismo error que ya se cometió con `sealed_remoto`. **Qué provee una imagen ajena es
238  diseño, compartido; qué instancias tiene tu disco, no.**
239
240Bedrock no puede decirte qué tenés. Nosotros sí, y esto cierra el riesgo real de todo el ADR: que en
241seis meses alguien cuente esas apps como parte del corpus. **En otra clase no se pueden contar mal.**
242
243### D6 — El caso Steam, que es el que ordena el diseño
244
245Steam **ya es un contenedor**: el cliente corre en el sistema y los juegos corren dentro de
246*pressure-vessel*, el contenedor bwrap de Valve con el runtime *sniper*. La forma correcta no es
247meter Steam en nuestra jaula sino anidarlas:
248
249```
250arje-zero → kwin (wayland)
251  └─ instancia glibc (tipo 1: drivers, libs de 32 bits, dnf)
252       └─ cliente Steam
253            └─ pressure-vessel (tipo 2, de Valve)      ← anidado
254                 └─ el juego + Proton
255```
256
257Corre mejor así porque **es la configuración exacta que Valve prueba**. Nosotros ponemos el nivel de
258afuera y la política; adentro no tocamos nada.
259
260⚠ **Verificar, no asumir:** pressure-vessel necesita crear user namespaces *desde dentro* de uno ya
261creado. El kernel los tiene encendidos, pero el anidamiento hay que probarlo con un juego real. Es
262la clase de cosa que sella verde y falla en la mano del usuario.
263
264### D7 — La política se escribe, y es la única vez
265
266harkaq deriva la política en vez de escribirla: `política = clausura(deps declaradas)`, y de ahí sale
267la evidencia negativa que hace valioso al subproducto ([SDD 16](../16-harkaq-jaula.md) §3).
268
269**Una imagen ajena no tiene clausura declarada.** Es el primer y único lugar del sistema donde la
270política hay que **autorarla**. No es un defecto: es una excepción que conviene nombrar y acotar en
271vez de descubrir. El bloque `[grants]` del manifiesto es esa política, **por defecto vacío**, y
272se compila al mismo `PolicySpec` que ya consume `harkaq-exec`.
273
274Un `dnf` que no alcanza `~/.ssh` es un argumento que ninguna distro ofrece.
275
276### D8 — Qué se pinea (el suelo, no la instancia) y cuántas imágenes se curan
277
278Dos preguntas que se confunden y tienen respuestas distintas.
279
280**a) Pinear no congela: fija el punto de partida.** El digest ES la identidad, igual que
281`alpine-minirootfs`, `zig` y el rootfs del lab. Lo que queda dentro y fuera del pin:
282
283| qué | ¿pineado? | cómo se actualiza |
284|---|---|---|
285| el rootfs base | **sí**, por sha256 | cambiar el digest en `instance.toml` + `hammer qorpa recreate` |
286| lo que instalás adentro (`dnf install steam`, `pacman -Syu`) | **no, y no puede estarlo** | con el gestor de la imagen, cuando quieras |
287
288Subir la base de versión es barato **precisamente por D3**: como el manifiesto es la verdad y el
289`upper/` es caché, se cambia `base = "sha256:…"` y se recrea. Sin D3 sería un rebase sobre un blob
290irreemplazable; con D3 son dos líneas y un rato de red.
291
292El riesgo real del pin —que upstream borre el tarball— **ya está resuelto por
293[ADR 0013](0013-mirror-de-fuentes.md)**: la URL no entra en la identidad, sólo el sha256, así que
294espejar una imagen es gratis y una imagen pineada no se puede perder.
295
296**b) Pinear ≠ lista cerrada.** `hammer qorpa pull <url> --sha256` acepta cualquier rootfs. Lo corto
297no es lo que *se puede* traer, sino lo que **nosotros probamos, espejamos y publicamos**, porque cada
298imagen curada es una segunda cadena de suministro que hay que sostener (§NO-resuelve 3). Se curan
299**tres**, y cada una entra por un trabajo distinto — no por sabor:
300
301| imagen | tipo | qué trabajo hace | pin |
302|---|---|---|---|
303| **Arch bootstrap** | 1 | juegos: `multilib` de 32 bits de primera clase, y SteamOS *es* Arch ⇒ extiende el argumento de D6 («la configuración exacta que Valve prueba») | `archlinux-bootstrap-2026.09.01-x86_64.tar.zst`, en `archive.archlinux.org` (archivado para siempre) |
304| **Ubuntu base LTS** | 1 | binarios comerciales: Zoom, Slack, Discord, Spotify, Chrome, JetBrains se compilan y prueban contra esto | `ubuntu-base-24.04.3-base-amd64.tar.gz`, `cdimage.ubuntu.com` + `old-releases` |
305| **Steam Runtime «sniper»** | 2 | la única **sellable**: al no mutar entra al store por `file_drop` y su digest va al índice firmado — cadena de custodia nuestra | ✅ **verificado 2026-09-03**: snapshot `3.0.20260805.254768` (el que despliega el cliente, no «el último»), imagen y depot |
306
307**Los digests enteros están en [`docs/state/qorpa-imagenes.toml`](../state/qorpa-imagenes.toml), no
308acá.** Estaban acá, abreviados —`895661bd…`— y cuando la poda se llevó las imágenes del disco no
309alcanzaron para volver a traerlas: hubo que ir a buscarlos otra vez a upstream. **Un pin que no se
310puede pegar en un comando no es un pin, es una cita.** El fichero además dice de qué lista de sumas
311salió cada uno y **si esa lista viene firmada**, que es la única forma honesta de hablar de una
312cadena de suministro ajena: Ubuntu firma su `SHA256SUMS`, Arch no firma la lista pero sí el tarball,
313y **Valve no firma nada** — su garantía entera es TLS más el pin.
314
315**Del sniper se pinean dos cosas, y la segunda es la que destraba el paso 6.** La imagen
316(`Platform-…-runtime.tar.gz`, un rootfs) y el **depot** `SteamLinuxRuntime_sniper.tar.xz`, que trae
317pressure-vessel más la imagen y es lo que Steam despliega en `steamapps/common/`. Ese runtime
318**sólo se baja al instalar un juego**, y eso pedía credenciales: pineado se coloca a mano, y
319pressure-vessel se puede ejercitar **sin cuenta, sin juego y sin pantalla**. El depot **no es un
320rootfs**: se trae con `--verify-only`, y traerlo a secas falla el anclaje en vez de adivinar
321(comprobado: «no encuentro un rootfs en el archivo»).
322
323**Fedora queda BYO, no curada.** No por calidad —publica `Fedora-Container-Base-Generic-43-1.6`
324con CHECKSUM firmado y se pinea igual de bien— sino porque hace el **mismo trabajo que Arch** en el
325slot «fresco», y una tercera cadena mutable es justo la normalización que §NO-resuelve 3 quiere
326evitar. El ejemplo de D3 sigue diciendo `fedora-43` a propósito: el mecanismo no distingue, y eso es
327la demostración de que la terna es una decisión de curaduría, no del diseño.
328
329**c) Compartibles, más adelante.** Una imagen pineada es cuerpo inmutable direccionado por
330contenido, así que **[ADR 0014](0014-distribucion-multiorigen.md) se le aplica sin cambiar nada**:
331puede servirse desde cualquier origen porque el digest la verifica, y ausencia ⇒ seguir mientras que
332contenido distinto ⇒ ABORTAR. No se hace el día uno, pero no hay que diseñar nada para que se pueda:
333lo único que falta es la decisión. ⚠ Antes de publicarlas a terceros (no a nuestras propias
334máquinas, que es lo que ya hace ADR 0013 con las fuentes) hay que mirar licencia y **marca**:
335redistribuir un rootfs de Ubuntu o Fedora sin modificar suele estar permitido, pero la política de
336marca es cosa aparte y no es una pregunta técnica.
337
338### D9 — Qué aporta harkaq a una instancia, y los dos conflictos que sólo se ven midiendo
339
340**Honestidad primero: en el eje del sistema de ficheros, harkaq casi no agrega nada.** El namespace
341de montaje de bwrap ya es una lista blanca —lo que no se bindea no existe adentro, y un `--ro-bind`
342es de sólo lectura por el kernel— así que escribir reglas Landlock que repiten eso sería un sello de
343goma. Por eso la política de una instancia **no sellada** es una sola línea (`rw /`) y no finge.
344
345Lo que harkaq sí aporta, y pesa mucho más con un binario ajeno y opaco que con nuestros propios
346builds:
347
348| aporte | por qué importa acá |
349|---|---|
350| **seccomp** | bwrap **no instala filtro alguno**: hoy una instancia puede `io_uring`, `bpf`, `ptrace`, `process_vm_readv`, `userfaultfd`, `keyctl`, `perf_event_open`, `init_module`, `kexec`. Ésa es superficie de kernel contra un prebuilt de terceros |
351| **`no_new_privs`** | ningún setuid de la imagen ajena escala adentro |
352| **canal de evidencia** | con Landlock ABI ≥ 7 el kernel audita las denegaciones ⇒ se puede saber **qué intentó tocar** un binario cerrado. Es la única forma de auditar el montón B. ✅ **cableado 2026-09-03**: `hammer qorpa run <id> --evidence` |
353| **`seal_image`** | lo único del eje fs que el namespace no da: congelar `/usr`, `/bin`, `/lib`, `/opt` **aunque adentro seas root**, para que un exploit no persista en el `upper` |
354
355**El canal de evidencia, cableado (2026-09-03).** `hammer qorpa run <id> --evidence` levanta el
356lector (`harkaq-audit`) en el HOST —el audit no está namespeceado y los registros cruzan— antes de
357que arranque la instancia, y al terminar imprime uno de **tres** estados. Los tres se verificaron a
358mano y quedan como guardián en `scripts/qorpa/evidence-probe.sh`:
359
360| estado | qué significa | comprobado con |
361|---|---|---|
362| **HERMÉTICO** | 0 denegaciones **y el canario las respalda** | una instancia que no toca nada prohibido |
363| **IMPURO** | qué intentó y no pudo — *el diagnóstico, no el fallo* | `touch /usr/INTRUSO; mkdir /opt/INTRUSO` → `fs.make_reg · /usr`, `fs.make_dir · /opt` |
364| **SIN EVIDENCIA** | no se pudo saber. **No es «limpio»** | quitándole las capabilities al lector |
365
366**El canario es lo que hace que «cero denegaciones» valga algo.** Es un fichero en un sitio que la
367política no alcanza; al leerlo, el kernel emite una denegación que revela el `domain=` de ESE
368dominio Landlock —un número que desde fuera no se puede adivinar—. Sin él, el lector no sabe cuáles
369de todas las denegaciones del sistema son de esta instancia, y `denials=[]` sería el instrumento
370callado en vez de una instancia limpia.
371
372**Dos condiciones estructurales, y `--evidence` FALLA en vez de dar un veredicto vacío si falta
373alguna:** con `nesting` no hay dominio Landlock (conflicto 1, acá abajo) ⇒ **o anidás o auditás**; y
374**sin `seal_image` la política es `rw /`, o sea que no hay nada denegable** ⇒ un veredicto limpio
375sería cierto por construcción y no por mérito. Ese acoplamiento no es un defecto de la
376implementación: *la evidencia sólo existe donde algo puede ser negado.*
377
378**Y una que salió midiendo el propio instrumento:** sin `CAP_AUDIT_READ` el kernel **responde que
379no** (`NLMSG_ERROR`/EPERM) y el lector ignoraba esa respuesta esperando una que no llegaría — 8 s
380por consulta, 16 s en su compuerta. Como `qorpa run` lo despierta al terminar, moría **por señal
381dentro de la compuerta, sin emitir nada**, y el veredicto quedaba vacío: un «no» tardío se parecía
382demasiado a un cuelgue. Ahora el `NLMSG_ERROR` se atiende y el lector dice su motivo en 2 s.
383
384**Conflicto 1 — Landlock y los contenedores anidados son incompatibles hoy.** Medido: con un dominio
385Landlock activo, `mount` falla con **EACCES aunque seccomp lo permita**; el kernel no admite montajes
386nuevos bajo un dominio, porque escaparían de sus reglas por-ruta. Es decir: **pressure-vessel no
387arranca bajo Landlock** (D6). Por eso `nesting = true` cuesta la política de ficheros —`harkaq-exec
388--allow-nesting --no-landlock`—, y **seccomp y `no_new_privs` siguen puestos**, que es lo que más
389pesa. Nunca por defecto y siempre dicho en la línea de arranque: harkaq no afirma una jaula que no
390puso.
391
392**Conflicto 2 — ~~`root` adentro y anidar se pelean~~, RESUELTO el mismo día.** Con el userns de un
393solo id que crea bwrap, `--uid 0` impedía que un userns anidado escribiera su `uid_map`: la
394instancia de juegos y la de gestor de paquetes querían mapeos **opuestos**. Con el mapeo por rango
395de §NO-resuelve 2 el conflicto desaparece —anida **con `root = true`**, verificado— y `root` deja de
396ser una elección incómoda. El campo se queda en el manifiesto porque sigue describiendo quién sos
397adentro, no porque haya que elegir entre dos males.
398
399**Y un detalle que ordena las expectativas:** bwrap **tira todas las capabilities**, así que dentro
400de una instancia no hay `CAP_SYS_ADMIN` — el anidamiento sólo puede ser por userns sin privilegios,
401que es exactamente como lo hace pressure-vessel.
402
403### D10 — Los tres muros que sólo aparecieron con Steam en la mano
404
405Ninguno estaba en el ADR, y los tres son de la clase «sella verde y falla en la mano del usuario»
406que §D6 nombraba sin poder anticipar.
407
408**1. La jaula mataba TODOS los binarios de 32 bits.** El filtro seccomp de harkaq comprueba
409`arch == AUDIT_ARCH_X86_64` y **mata** lo que no lo sea. Para un build es la defensa clásica y
410correcta —los números de syscall son por arquitectura—; para el montón B es fatal, porque el cliente
411de Steam es un ELF i386. El síntoma medido fue `ldd: exited with unknown exit code (159)` — **159 =
412128+31 = SIGSYS** — que no se parece en nada a «tu jaula mata los 32 bits». La salida no es aflojar
413el check (eso reabre el agujero) sino **darle a i386 su propia tabla y aplicarle la misma política**.
414Los 25 números van literales y se verificaron **uno por uno contra `/usr/include/asm/unistd_32.h`**:
41524 estaban bien y **uno mal** — `kexec_file_load` no existe en i386, y su número de x86_64 (320) es
416ahí `utimensat`, o sea que habríamos denegado algo que usa cualquier cosa que toque una marca de
417tiempo. Es la diferencia entre una tabla escrita de memoria y una verificada.
418
419**2. Steam se niega a correr como root**, y cambiar el mapa para evitarlo **corrompe la instancia.**
420`bin_steam.sh: Error: Cannot run as root user`. La vía tentadora es mapear el uid 1000 en vez del 0
421—el mapa decide quién sos—, pero **un fichero creado bajo un mapa aparece con OTRO uid bajo el
422otro**: el `useradd` de la preparación deja un `/home` que después su propio dueño no puede escribir
423(`mkdir: /home/jugador/.steam: Permission denied`). ⇒ el mapa es parte de la IDENTIDAD de la
424instancia y cambiarlo pide `recreate`. La vía correcta es la de cualquier runtime de contenedores:
425**un solo mapa, y se BAJA de privilegio adentro** (`run_as` en el manifiesto, `setpriv`, con el
426`CAP_SETUID` que ya tenemos en el namespace).
427
428**3. El `XDG_RUNTIME_DIR` es del usuario que CORRE, no del uid del mapa.** Con `run_as`, apuntarlo
429al de root deja a las herramientas del Steam Runtime sin poder crear su temporal
430(`srt-logger: g_mkdtemp: Permission denied`). Se lee como un aviso menor hasta que algo deja de
431andar sin explicar por qué.
432
433**Lo que sí quedó probado, y es el corazón del ADR:** un userland glibc ajeno con su cadena de 32
434bits completa corre enjaulado sobre nuestro kernel, con seccomp y `no_new_privs` puestos, y **un
435contenedor anidado funciona adentro** — que es la forma exacta en que Valve prueba Proton.
436
437### D11 — El proxy de Wayland: lista BLANCA, y por qué al revés que las syscalls
438
439El compositor anuncia **todos** sus globals a quien se conecte. El proxy se mete en el medio, relaya
440todo salvo dos mensajes y con eso alcanza:
441
442| mensaje | qué se hace | por qué |
443|---|---|---|
444| `wl_registry.global` (del compositor) | si el interface no está en la lista, **no se reenvía** | el cliente nunca se entera de que existe |
445| `wl_registry.bind` (del cliente) | si el `name` es uno de los ocultos, `wl_display.error` y se corta | el `name` es **un número que se puede adivinar**: ocultar sin cortar el bind dejaría el filtro en decorativo |
446
447**Lista blanca, al revés que la denylist de syscalls de harkaq, y la asimetría tiene razón:** el
448conjunto *peligroso* de Wayland **crece** —cada compositor inventa protocolos privilegiados— mientras
449que el conjunto *necesario para dibujar una ventana* es corto y estable. Una denylist estaría
450desactualizada el día que alguien actualice el compositor, **y sin un solo error visible**. La lista
451incluye a propósito lo que los juegos piden y suele olvidarse: `pointer_constraints`,
452`relative_pointer`, `tearing_control`, `idle_inhibit`.
453
454**Lo que hace esto viable en un fichero:** ningún mensaje que se descarta lleva descriptores, así que
455los fds (que Wayland pasa por `SCM_RIGHTS` para `wl_shm` y dmabuf, y sin los cuales no se dibuja
456nada) se relayan en orden de llegada **sin tener que asociarlos a su mensaje**.
457
458**Probado sin compositor**, con uno FALSO que anuncia siete globals —tres permitidos y cuatro
459peligrosos— y un cliente que cuenta lo que ve: pasan exactamente los tres, y el intento de bindear
460por número el `name` que nunca se anunció corta la conexión. Es la clase de prueba que no necesita
461GPU y aun así responde la pregunta entera. Un quinto test cubre el `size` menor que la cabecera, que
462haría avanzar 0 bytes y colgar el proxy en un bucle.
463
464---
465
466## Lo que este ADR admite que NO resuelve
467
468Se escriben acá para que no se descubran en producción.
469
4701. **El socket de Wayland — ~~el agujero~~ CERRADO 2026-09-03.** Se escribió el proxy que faltaba
471   (D11): la instancia ya no ve el registro entero del compositor sino una **lista blanca**. Lo que
472   queda del párrafo original es la razón por la que se hizo: pasar el socket crudo **no es abrir un
473   caño, es un borde de privilegio** — `screencopy` captura la pantalla, `virtual_keyboard`
474   sintetiza teclas, `data_control` lee el portapapeles sin que nadie copie y `layer_shell` dibuja
475   encima de todo. Sigue disponible con `wayland_raw`, apagado por defecto y avisando a gritos.
476
4772. **UID mapping — ~~el muro~~ RESUELTO 2026-09-03.** Este punto ya no describe un hueco; queda
478   por lo que enseñó. La instancia veía `uid_map: 0 1001 1` y `setgroups: deny`, y eso rompía `apt`
479   (no podía bajar a `_apt`), `pacman` (no podía chownear su descarga a `alpm`) y el userns anidado
480   de pressure-vessel. **Tres síntomas, una causa.**
481
482   La cura entera —`hammer qorpa run` la aplica sola cuando puede— tiene **tres partes, y ninguna
483   sobra**:
484
485   | pieza | por qué |
486   |---|---|
487   | `setcap cap_setuid+ep newuidmap` (y `cap_setgid` en `newgidmap`) | el binario está en el corpus (`recipes/shadow.toml`) pero **sin provisionar**; sin la capability no puede escribir el mapa |
488   | crear el userns **nosotros**, mapear el rango de `/etc/subuid` y pasárselo a bwrap con `--userns FD` | bwrap crea el suyo con **un solo id a propósito** y nunca llama a `newuidmap`: el trabajo es de quien lo invoca |
489   | devolver las **capabilities** dentro del namespace (`--cap-add`) | **bwrap las tira todas**, y en Linux ser root es tener `CAP_SETUID`, no tener uid 0. Sin esto `apt` sigue sin poder `seteuid(42)` — un síntoma que *parecía* de subuid y no lo era |
490
491   Con las tres: `uid_map` de **65537 ids**, `setgroups: allow`, `apt` instala **sin** el
492   `APT::Sandbox::User=root`, `pacman` sincroniza con `DownloadUser = alpm` **intacto**, y el
493   userns anidado monta **con `root = true`** ⇒ el conflicto 2 de D9 se disuelve. Las capabilities
494   concedidas son seguras por construcción: dentro de un user namespace sólo alcanzan a lo que ese
495   namespace posee, o sea nuestros propios subuid. `CAP_SYS_ADMIN` queda fuera y cuelga de `nesting`.
496
497   **Y una consecuencia que sólo aparece después:** el `upper/` pasa a contener ficheros de los
498   subuid (apt deja los suyos con uid 165577) que **nuestro uid normal no puede borrar** ⇒
499   `recreate` y la poda tienen que entrar a un userns mapeado para limpiar
500   (`unshare -U --map-auto -r rm -rf`). Quitar el impuesto mueve el problema, no lo evapora.
501
5023. **Segunda cadena de suministro, sin ninguna garantía de hammer.** Sin repro, sin cierre firmado,
503   sin escaneo de licencias. El riesgo no es técnico: es que se normalice. Mitigación = D5 capa 3
504   (clase `ajeno` en el grafo) + un renglón explícito en [SDD 20](../20-catalogo-publicable-y-completa.md):
505   **las imágenes ajenas no entran en el catálogo publicable ni en el reporte de licencias, porque
506   no podemos enumerarlas.**
507
5084. **El alcance del claim.** Desde el día que exista una instancia, la frase «hammer reproduce bit a
509   bit» hay que acotarla por escrito: *el sistema base reproduce; las instancias ajenas no, y se
510   declaran como tales*. Sin eso, la cultura de números honestos se erosiona sola — que es
511   exactamente la falla que ya nos pasó con el store-gc y con la deuda fantasma.
512
5135. **Disco.** Un rootfs de Fedora son 1-2 G y no lo alcanzan `store-gc` ni `.dmerge`. Necesita poda
514   propia. Este repo ya tuvo tres emergencias de disco; que la poda nazca con el subsistema, no
515   después.
516
5176. **Red adentro.** `dnf` la necesita. Es la concesión más peligrosa del manifiesto y por eso es la
518   única que se escribe sola en una línea aparte. También hace falta `/etc/resolv.conf`: es el
519   segundo fallo clásico de la primera corrida.
520
5217. **X entre instancias.** Un Xwayland dentro de una instancia levanta *su* servidor X. Portapapeles
522   con el escritorio funciona (pasa por el compositor); entre dos instancias, no. Aceptado.
523
524---
525
526## Lo que se cae, y lo que se resuelve gratis
527
528- **`xwayland` deja de ser deuda del corpus.** Si las apps X sólo corren dentro de instancias, el
529  Xwayland va **adentro de la imagen** —Fedora y Arch ya lo traen— y se cuelga de nuestro kwin por
530  el socket. El nodo `wanted` de `escritorio-kde` se disuelve sin escribir la receta y sin tocar la
531  postura Wayland-only. `targets.toml` debe sacarlo de las raíces con una nota que apunte acá.
532- **GIMP e Inkscape dejan de reabrir GTK3.** Son GTK3 y GTK3 está aparcado a propósito
533  (ver la memoria del frente GNOME). Con instancias, corren sin traer el árbol GTK3 al corpus.
534- **F2 del plan de juegos, cancelada.** Las libs de 32 bits las trae la imagen.
535- **F0 del plan de juegos, innecesaria.** No hace falta meter flatpak+ostree al catálogo para tener
536  juegos.
537
538## Lo que este ADR NO cambia
539
540- **El montón A se sigue construyendo nativo.** La jaula es para binarios ajenos, no una excusa para
541  no empaquetar. Orden acordado: **mpv → OBS → Firefox**.
542- **Wayland-only sigue en pie**, y este ADR es lo que lo hace barato.
543- **arje-zero sigue siendo PID 1.** Nada de integración a nivel de init, que es una de las formas de
544  Bedrock que se rechazan explícitamente.
545- **Cada instancia se gestiona con su propio gestor**, entrando explícitamente. Nada de multiplexar
546  `dnf`/`pacman` detrás de un comando único (el `pmm` de Bedrock): es menos mágico y no miente.
547
548---
549
550## Orden de trabajo propuesto
551
5521. **Provisionar subuid** y probar `dnf install` en una instancia mínima. Es lo primero que falla
553   (§NO-resuelve 2) y define si el resto es fácil o difícil.
5542. ✅ **HECHO 2026-09-03.** `hammer qorpa pull <url> --sha256` + verificación de digest antes de
555   desempacar. El rootfs se ancla por estructura (`etc/` + `usr|bin`), con `--subdir` de escape.
5563. ✅ **HECHO 2026-09-03.** Instancia = overlay sobre la imagen + `instance.toml`; `create` /
557   `recreate` / `run`. El overlay lo monta bwrap (`--overlay-src` + `--overlay`) dentro de su
558   propio namespace: sin root y sin montar nada en el host. `run` entra con `--clearenv` y con
559   `--unshare-net` salvo que se declare `network` — el entorno del host también es una concesión.
560
561   **Corregido el mismo día, y el bug era una verdad a destiempo:** dos `run` seguidos sobre la
562   misma instancia y el segundo moría con `Can't make overlay mount … Device or resource busy`; el
563   tercero andaba. El kernel se **niega a propósito** a montar dos overlays vivos que compartan
564   `upperdir`/`workdir` —eso corrompe la capa—, así que el EBUSY es un guardián correcto: lo que
565   estaba mal era el momento, porque la corrida anterior ya devolvió el prompt y su namespace
566   todavía no terminó de reaparse. Ahora `run` reintenta acotado y, si el overlay sigue tomado,
567   dice **la causa** («¿hay otra `run` viva?») en vez de dejar pasar el mensaje crudo de bwrap.
5684. ✅ **HECHO 2026-09-03.** Concesiones → política de harkaq. `harkaq-exec` entra como último
569   eslabón dentro de bwrap (cruza un binario **estático**, no una librería ⇒ D2 sigue en pie), y
570   aporta lo que bwrap no da: **seccomp** —hoy una instancia podría `io_uring`, `bpf`, `ptrace`,
571   `userfaultfd`, `keyctl`, `perf_event_open`—, `no_new_privs`, y el canal de evidencia. Ver D9.
5725. ✅ **HECHO 2026-09-03.** Shims + `.desktop` generados (`export`), y clase `ajeno` en
573   `build-state.py`. El `.desktop` se genera con lista BLANCA de claves —`Exec`, `TryExec`, `Path`,
574   `DBusActivatable` quedan fuera **por definición**, no por enumeración— y el icono se copia al
575   host, porque un icono que el host no resuelve se ve como un cuadrito gris. Cada fichero escrito
576   queda en un registro (`exported.json`) para que `--remove` borre **exactamente** lo generado y no
577   por patrón sobre el `~/.local/bin` de alguien.
5786. ⚠️ **PARCIAL 2026-09-03** — hasta donde esta máquina permite, y destapó tres muros. Steam
579   1.0.0.87 **instalado de verdad** desde el `multilib` de Arch (las libs de 32 bits que la F2
580   daba por «una campaña entera»), su cliente i386 **bajado y desempacado** por el propio
581   bootstrap de Valve, y el **bwrap anidado verificado explícitamente** (`BWRAP-ANIDADO-OK`, 24
582   montajes propios) — que era lo que este paso pedía. Ver D10.
583
584   **Lo que NO se pudo, y por qué:** la máquina no tiene ninguna sesión gráfica (`/dev/dri` sí,
585   socket Wayland no), así que Steam no dibuja; y el runtime *sniper* sólo se baja al instalar un
586   juego, lo que exige credenciales. **pressure-vessel con un juego real sigue sin ejercitarse.**
587
588   **✅ AMPLIADO 2026-09-03: pressure-vessel SÍ se ejercitó — sin cuenta, sin juego y sin pantalla.**
589   Lo que lo destrabó fue pinear el depot (D8): `SteamLinuxRuntime_sniper.tar.xz` es lo que Steam
590   despliega, y colocado a mano no hace falta comprar nada. Corrido dentro de una instancia qorpa
591   *sobre Ubuntu base*, con `nesting` y la jaula puesta:
592
593   | evidencia | fuera de pressure-vessel | dentro |
594   |---|---|---|
595   | `/etc/os-release` | `Ubuntu 24.04.3 LTS` | **`Steam Runtime 3 (sniper)`** |
596   | namespace de montaje | `mnt:[4026532468]` | **`mnt:[4026532526]`** |
597   | `/usr/lib/x86_64-linux-gnu` | el de Ubuntu | **675 libs de sniper, `libSDL2-2.0.so.0` incluida** |
598
599   O sea: **contenedor de Valve anidado dentro de nuestra jaula, con el runtime real adentro.** Es
600   la pregunta que ordenaba D6 y ya no está abierta.
601
602   **Y la concesión resultó ser de verdad, no un adorno:** con `nesting = false` el mismo comando
603   muere en `bwrap: Creating new namespace failed: Operation not permitted`. Una concesión que no
604   se puede apagar no es una concesión.
605
606   Tres detalles que sólo salen corriéndolo: pressure-vessel avisa `Cannot determine ld.so for
607   i386-linux-gnu` porque Ubuntu base no trae multilib —para juegos la base es Arch, que es
608   justamente por lo que Arch está en la terna—; `ldd --version` sigue diciendo la glibc de la
609   instancia y **está bien**, porque pressure-vessel importa la libc del host cuando es más nueva
610   que la del runtime, así que la prueba de que el runtime entró es `os-release`, no `ldd`; y no
611   hay ICD de Vulkan porque no se concedió `/dev/dri` — la jaula no regala dispositivos.
612
613   **Lo que sigue faltando, y ahora es sólo esto:** un juego real dibujando, que pide sesión
614   gráfica y credenciales. Ninguna de las dos es una pregunta de diseño.
6157. ✅ **HECHO 2026-09-03.** `hammer qorpa prune` + el renglón en
616   [SDD 20](../20-catalogo-publicable-y-completa.md#imágenes-ajenas-qorpa-fuera-del-catálogo-y-por-escrito).
617   Poda restos de pulls a medias, imágenes que ninguna instancia usa (se re-traen por digest: es la
618   propiedad que da el pin) y, con `--upper`, las capas mutables. **Sin `--yes` es un simulacro**, y
619   tras borrar **comprueba que el directorio se fue**: la cicatriz de `store-gc`, que reportaba
620   borrados que no ocurrían. Los tamaños de un árbol con directorios ilegibles se marcan con `≥`,
621   porque un número silenciosamente bajo es peor que ninguno cuando con él se decide borrar.
6228. ✅ **HECHO 2026-09-03.** Proxy filtrante de Wayland. Ver D11.
623
624## Nombre — ADOPTADO 2026-09-03
625
626El subsistema se llama **`qorpa`** — *huésped alojado*: alguien que entra a la casa, se le dan
627habitaciones concretas y no las demás. Elegido por el autor del repo; entra en la familia (harkaq,
628yupana, arje, wawafs, kikin, churay, mirada, minga).
629
630Consecuencias de nombre, ya aplicadas arriba: la frontera es `hammer qorpa {…}`, el espacio de
631nombres es `/var/lib/hammer/qorpa/{imagenes,instancias}/` —uno solo, para que la poda de
632§NO-resuelve 5 tenga un único árbol que barrer— y el adjetivo del grafo sigue siendo `ajeno`
633(clase de nodo), porque describe la **procedencia** del nodo, no el subsistema que lo aloja.