hammer/docs/adr/0012-arbol-de-fuentes-compartido-vs-privado.md

ADR 0012 — El árbol de fuentes es caché y workspace a la vez: carrera abierta en fetch

• Estado: PENDIENTE — dilema abierto, sin decidir. No implementar sin resolverlo (ver §Opciones).
• Fecha: 2026-07-22
• Frontera: crates/hammer-build/src/fetch.rs (fetch_tarball / fetch_git), crates/hammer-build/src/lib.rs:208. Mitigación parcial ya en árbol: commit 1b436a7.

Contexto

fetch nombra el árbol de fuentes de forma determinista y sin componente por-constructor:

let work_tree = sources_dir.join(format!("{}-{}", recipe.name, &sha256[..16]));
if work_tree.is_dir() { std::fs::remove_dir_all(&work_tree)?; }
std::fs::create_dir_all(&work_tree)?;
// tar -x dentro de work_tree

Dos procesos que construyan la misma receta (típicamente la misma dep alcanzada por dos caminos) resuelven al MISMO directorio. Uno hace remove_dir_all mientras el otro corre tar -x: el árbol queda a medias y devuelve Directory not empty (os error 39) — y se queda roto hasta que alguien lo borra a mano, porque el siguiente intento vuelve a chocar igual.

No es teórico. El 2026-07-22 la campaña de deuda y el worker-loop pidieron mesa a la vez (el loop lo arrastraba desde la cola KDE al invalidarse libdrm) y se llevó puesta media cascada GUI, con un error que no nombra la causa.

Lo que YA está mitigado (no rehacer)

Un lock compartido de grano grueso entre campana-deuda.sh y farm-worker-loop.sh (work/.farm-build.lock, commit 1b436a7): la campaña lo retiene toda su corrida, el loop por ciclo de cola. Verificado: la carrera entre esos dos scripts desapareció.

Lo que NO cubre

build-farm.sh lanza xargs -P2: dos recetas de la misma cola que compartan dep se siguen pisando exactamente igual. El lock entre scripts no puede cubrir esto sin serializar el -P2 y tirar el paralelismo del worker.

El dilema

El árbol cumple dos papeles que se contradicen bajo concurrencia:

1. Caché direccionada por contenido — la clave es (nombre, sha), así que dos builds de la misma dep "deberían" compartirlo, y re-extraer es caro.
2. Workspace mutable de build — lib.rs:208-234 lo MUTA en el sitio: apply_patches, ensure_cargo_workspace_isolation, vendor_cargo_deps (que para Go/Cargo puede tardar minutos y ocupar decenas de GB), y después el sandbox lo bind-montea para compilar.

Por eso un lock sólo alrededor de la extracción NO alcanza: aunque serialice el tar, un segundo proceso puede hacer remove_dir_all sobre un árbol que un bwrap está usando para compilar. La protección tiene que cubrir extracción y build, o los papeles tienen que separarse.

Opciones (ninguna elegida)

A. Lock por árbol sostenido durante TODO el build (extract → patch → vendor → compile → seal). Correcto y contenido (un lock en fetch + guard hasta el final de build). Contra: serializa cualquier par de builds que necesiten la misma receta. El grafo es un diamante que converge —el propio código lo dice: "TODO KF6/Qt converge en qtbase/kcoreaddons, alcanzable por decenas de rutas"— así que puede degenerar en serializar casi todo y matar el -P2.

B. Árbol privado por build (sufijo único por invocación). Elimina la carrera por construcción, sin lock ni serialización. Contra: re-extrae y re-vendorea por build. El go mod vendor ya está documentado como el cuello real del worker (decenas de GB sin tope, el watchdog de disco existe por eso, DISK_HIGH=82). Esta opción empuja justo donde ya duele.

C. Separar los dos papeles: caché inmutable (sources-cache/<nombre>-<sha>, extraída una vez bajo lock y nunca mutada) + copia privada por build. Es la respuesta principista: cada papel con su ciclo de vida. Contra concreto: el worker corre ext4, que no tiene reflink (cp --reflink es btrfs/xfs), y hardlinkear no sirve porque el build muta en el sitio y corrompería la caché ⇒ la copia es real, con su coste en disco y tiempo. Reevaluar si el store vivo del SDD 18 (composefs) cambia el piso.

Qué haría falta para decidir

Medir, no opinar:

1. Cuántos pares (receta, receta) de una misma cola comparten dep de verdad ⇒ cuánto serializaría la opción A en la práctica.
2. Coste real de re-extraer + re-vendorear las recetas más caras (Go/Cargo grandes) ⇒ cuánto cuesta B por build.
3. Espacio pico de la opción C con el corpus actual, contra el DISK_HIGH del watchdog.

Sin esos tres números, cualquiera de las tres se elige a ciegas.

Nota de coordinación

Hay otro agente trabajando sobre este repo. Este ADR existe para que la carrera quede registrada y nadie la "arregle" a medias: un lock sólo en la extracción parece correcto y no lo es (§El dilema). Si vas a tocarlo, resolvé el dilema primero.