takana/docs/BRIEFING-takana.md

takana — informe de arquitectura completo (briefing para un agente externo)

Para qué es este documento. Dar a un modelo que NO tiene acceso al repositorio el contexto suficiente para razonar sobre takana al nivel de proponer SDDs nuevos: arquitectura, capas, componentes, invariantes, decisiones tomadas, estado real medido, deuda abierta y las lecciones de método que este proyecto pagó caro.

Fecha de corte: 2026-08-28. Todo número marcado (medido) salió de un comando corrido ese día contra el repo; los demás llevan la fecha del documento del que vienen.

Idioma y convención: el repo entero está en español, incluidos commits, docs y comentarios. Los SDD son documentos de diseño numerados (docs/NN-*.md); los ADR son decisiones (docs/adr/NNNN-*.md). Cuando el código y el SDD discrepan, o se corrige el código o se actualiza el SDD con un commit que explica por qué.

---

0. Resumen ejecutivo en diez líneas

takana es una distribución Linux + su gestor de construcción, escrita en Rust, cuya tesis es separar dos mundos hoy fusionados:

• El sótano (el laboratorio): compilación determinista, hermética y direccionada por contenido (BLAKE3). bubblewrap + zig cc + musl. Cada artefacto es un árbol de ficheros sellado bajo su hash de entrada.
• El piso de arriba (el userland): un Linux clásico, mutable, con FHS real (/bin, /lib, /etc). Los binarios se hidratan desde el store por hardlinks.

Entre ambos viven tres piezas propias: overlay de experimentación (try/commit/discard), diario de mutaciones por fanotify (la configuración se deriva a posteriori, no se declara antes), y el .swm, un manifiesto de mutación que viaja en vez del binario — el receptor reproduce y verifica. Encima corre un bus de agente (/run/agent.sock) por el que una IA propone, construye, prueba en overlay y presenta; el humano hace commit.

El proyecto ya cerró el bucle AI-nativo completo, el bootstrap auto-alojado bit-reproducible (incluido el toolchain y el kernel), cuatro escritorios construidos desde fuente, formato de paquete/repositorio/instalador, imágenes ISO/USB/EFI e infraestructura de granja de compilación. Lo que falta para publicar es sobre todo legal, de claves y de validación en metal.

---

1. Filosofía y anti-objetivos (SDD 00)

El problema. Las distros inmutables/declarativas (NixOS, Guix, Silverblue) dan determinismo a costa de agencia: el SO es el grafo, se pierde la estructura familiar y la IA tiene que simular a un humano tras capas de abstracción. Las tradicionales (Arch, Gentoo) dan control pero se pudren: el gestor pierde el rastro de lo que el usuario hizo a mano.

La tesis. «La automatización funcional es mi empleada en el sótano. En el piso de arriba mando yo.» Determinismo en la fábrica, libertad en la ejecución; ninguno de los dos se negocia.

Por qué es AI-nativo (el diferenciador real, no la distro en sí):

1. Compilación determinista ⇒ la IA cambia fuente, recompila, y el binario es predecible.
2. El sistema ejecutable es texto plano + binarios atómicos ⇒ nada de bases de datos binarias opacas (registro, journal binario). Se lee con cat, grep, readelf.
3. Mutabilidad = agencia real, con overlay como red de seguridad.
4. musl mantiene el C legible para el contexto de un LLM (glibc es un laberinto de macros).
5. El enlazado estático evita que mutar una herramienta rompa las librerías de otra.

Principios. Verificar, no confiar · texto plano por encima de bases opacas · la IA propone, el humano dispone · no reinventar lo resuelto · el diario es la verdad (se vive imperativamente y el estado declarativo se deriva después, nunca al revés).

Anti-objetivos. No es un gestor inmutable; no reescribe un motor de build (ADR 0004: takana NO usa nix); no compila contra HEAD vivo (ADR 0006); no oculta complejidad tras abstracciones.

---

2. Arquitectura general (SDD 01)

2.1 Modelo de dos mundos

   EL SÓTANO (laboratorio)                    EL PISO DE ARRIBA (userland)
   determinista · hermético                   mutable · clásico · FHS real

   upstreams (commits/tarballs FIJADOS)
        │
   takana-build (bwrap + zig cc)   ──sella──▶  CAS store  ──hidrata──▶  /bin /lib /etc
   recetas + grafo de deps                    /store/<b3>-<name>/       (hardlinks)
                                                   │                        │
                                                   ▼                        ▼
                                            overlay try/commit      diario fanotify
                                                   │                        │
                                     BUS DE AGENTE /run/agent.sock (JSON-líneas)
                                     COMPILE · INJECT · QUERY · eventos
                                                   ▼
                                            [ IA programadora ]

Regla de oro: los dos mundos nunca se mezclan. El lab jamás escribe en el FHS real (pasa por store + hidratación); el userland jamás compila contra el host (delega al lab).

2.2 Los crates (workspace Rust, edición 2021, opt-level="z" + lto + panic=abort)

Crate	Responsabilidad única
takana-core	Tipos compartidos: Recipe, Swm, Store, ArtifactHash, proto (bus), repo, sign, installed, compat (slots), query, differs, lab, apply, caps, y el módulo kernel/ (SDD 22)
takana-build	El laboratorio: sandbox (bwrap), fetch, download, hydrate, swm_bridge, harkaq (la jaula), config
takana-bootstrap	Orquesta stage0/stage1/stage2/builder/all + manifest (log de transparencia)
takana-overlay	try/commit/discard/status sobre overlayfs, con apilamiento LIFO
takana-journal	Diario append-only JSON-líneas, content_hash, de-dup idempotente
takana-mirror	Replicación del store por hash entre máquinas (verifica of_tree al recibir)
takana-upgrade	Generaciones, apply/rollback/prune/recover, boot_graph (ADR 0010)
hammer-recover	Mini-binario estático que auto-sana un upgrade interrumpido, al arranque
takana-agent	AgentClient, IntentTranslator (+ MockTranslator, ClaudeTranslator), Orchestrator
takana-cli	El binario takana (+ alpine_import, nix_import, kernel_cmd)
hammerd	Daemon: bus de agente, watcher fanotify, FIFO de init, crashes, arje_link
netup	DHCP/netlink mínimo para el producto

2.3 Estado en disco

/store/<blake3>-<name>/     artefacto sellado, inmutable, append-only
/var/lib/hammer/
  recipes/  pins.toml  journal/  overlays/  trust/  installed.json  upgrades/
/run/init.control           FIFO de control humano (texto crudo)
/run/agent.sock             socket de agente (JSON-líneas, SO_PEERCRED)
/run/hammer/boot-graph.json grafo de estados que dibuja el menú de arranque (ADR 0010)

---

3. Definiciones canónicas (lo que hay que entender para proponer cambios)

3.1 Recipe — el átomo del grafo

TOML declarativo y puro. Campos reales (takana-core/src/recipe.rs):

name = "grep"
version = "3.12"
license = "GPL-3.0-or-later"     # FUERA de hash_inputs (ver §3.2)

[source]
repo = "…" ; commit = "…"        # git  … XOR …
tarball = "…" ; sha256 = "…"     # tarball
strip_components = 1
patches = ["…patch"]
cargo_vendor = true              # perilla del vendoreo Cargo
cargo_vendor_dir = "…"           # cuando el proyecto ya trae su vendor/

[build]
compiler = "zig-cc"              # "zig-cc" | "clang" | "gcc"
target   = "x86_64-linux-musl"
link     = "static"              # "static" | "dynamic"
flags    = [...]
zig_version = "0.13.0"           # pin opcional (84 recetas lo fijan)
strip_debug = true               # separa .debug_* (SDD 23) — SÍ entra al hash
cgo = false
subdir = "…"
[build.phases] configure/compile/install  # overrides opcionales

[deps] build = [...] ; runtime = [...]
[evidence] checks = [...]        # H1 proof-carrying (fuera del hash)
[slots] claims = {...} ; requires = {...}   # H4 compatibilidad (fuera del hash)

3.2 ArtifactHash — hash de entrada, no de salida

artifact_hash = BLAKE3(
      source_id            // "git:<commit>" XOR "tarball:<sha256>"
    ⧺ compiler ⧺ target ⧺ link
    ⧺ lab:<LabFingerprint>          // ← desde 2026-08-10
    ⧺ [zig:<version>]  si está fijado
    ⧺ [strip_debug:<bool>] si está fijado
    ⧺ contenido de cada patch
    ⧺ cada flag
    ⧺ phase:configure/compile/install si hay override
    ⧺ Σ dep.artifact_hash )

Consecuencias que gobiernan casi todas las decisiones del proyecto:

• hash_inputs es una LISTA BLANCA. Lo que no está enumerado no mueve el hash. Por eso license, evidence y slots se pudieron añadir sobre recetas ya selladas sin re-hashear nada. Es el truco recurrente para pagar deuda barata.
• Las fases de build SÍ entran. ⇒ editar el -j de una fase cambia el hash aunque el binario sea idéntico; ⇒ el .config del kernel (que vive en la fase configure) es la identidad del artefacto (SDD 22 §1); ⇒ strip_debug obliga a re-hashear el corpus (SDD 23).
• El hash es de entrada, no de contenido. takana hash <receta> responde en ~2 ms cuál es el hash VIGENTE sin construir; --check dice si ya está sellado. ArtifactHash::of_tree es la otra cosa: el hash del contenido real de un árbol, usado para verificar reproducibilidad y para el mirror.
• Corolario peligroso: strip posterior al sellado rompería la verificación bit-a-bit, porque el hash de entrada seguiría apuntando a algo que un rebuild ya no reproduce.

3.3 LabFingerprint — el toolchain como entrada (2026-08-10)

Se computa del apk db del rootfs real que va a compilar (no de un fichero declarado). Entran compiladores/enlazadores (gcc, clang, llvm, binutils, rust, cargo), las libs de codegen de gcc (gmp, mpfr, mpc, isl), el runtime que se enlaza dentro (musl, libgcc, libstdc++, libatomic, libgomp) y los headers que se compilan dentro (linux-headers, fortify-headers). Quedan fuera a propósito autotools y shells: es una decisión de coste, no una afirmación de que no influyen.

Por qué existe: reconstruyendo los cuatro kernels en un segundo hub, el .config instalado salió distinto en 4 líneas (CONFIG_RUSTC_VERSION 109600→109700) — Rust 1.96 vs 1.97 del rootfs, y Rust ni siquiera estaba activado en ese kernel. Antes de esto, dos labs sellaban bytes distintos en la MISMA dirección y el store no podía notarlo.

3.4 Store, hidratación, overlay, diario

• Store: inmutable, append-only, deduplicado, GC por alcanzabilidad (scripts/store-gc.sh distingue SUPERADO —hay ejemplar mejor— de HUÉRFANO —ejemplar único—). Store::has rechaza directorios vacíos (un vacío es un nombre, no un artefacto).
• Hidratación (ADR 0005): hardlink directo en el caso estático; en el dinámico se copia y se reescribe con patchelf --set-interpreter/--set-rpath (no se hardlinkea, o patchelf mutaría el inode del store). Escribir encima rompe el hardlink ⇒ el store queda intacto como base de rollback.
• Overlay (SDD 04): overlayfs con upperdir mutable sobre el FHS real. try/commit/ discard/status. El apilamiento es total y determinista (created_at + id + seq) y commit/discard exigen LIFO (Error::Shadowed si una capa más joven sombrea el target).
• Diario (SDD 05): fanotify (FAN_CLOSE_WRITE) sobre /bin,/sbin,/usr/bin,/usr/sbin, /lib,/usr/lib,/etc; JSON-líneas append-only; op ∈ {Create, Edit, Delete} derivado por classify_op; content_hash tras la mutación con de-dup idempotente. Distingue mutación trazable (vino de un artefacto conocido) de opaca (pisada a mano) sin prohibir ninguna.

3.5 .swm — la unidad de intercambio (SDD 06)

YAML con base (distro_version + pins), mutations y signature opcional (Ed25519). Cuatro tipos de mutación: source_patch (una Recipe serializada para viajar), config_edit (hunks exactos, sin fuzz), init_rule y file_drop (content_b64 XOR content_url, siempre con content_hash BLAKE3 verificado antes de escribir nada).

takana apply verifica base → verifica firma → reproduce en el lab local → aísla en overlay → el humano valida → commit. Nunca se ejecuta un binario ajeno.

3.6 Repositorio de paquetes (Etapa F)

Un repo son ficheros estáticos: index.json + los .swm. Un .swm no tiene identidad propia; la identidad la asigna el índice al publicar (el índice es el namespace). install <nombre> resuelve el cierre transitivo de build-deps del índice (topológico), sintetiza un catálogo de recetas efímero desde los .swm de las deps y reproduce desde fuente. El índice entero se firma como release (cualquier pack --repo la invalida ⇒ re-firmar). Consumible por HTTP(S).

---

4. El laboratorio de build (SDD 02)

4.1 El sandbox

bubblewrap con --unshare-all (net, pid, mount, ipc, uts, user). Base y deps montadas read-only con --overlay-src + --tmp-overlay /; las únicas superficies RW son /src (árbol de fuentes, bind) y /out (DESTDIR). Entorno mínimo y fijado: SOURCE_DATE_EPOCH, CC, -mcpu=baseline, CARGO_BUILD_JOBS=1, CARGO_PROFILE_RELEASE_CODEGEN_UNITS=1.

Sin red dentro del sandbox. El fetch ocurre fuera. Corolario que aparece una y otra vez: el build es offline por construcción, así que su clausura no contiene las clases de servicio del mundo (DNS, TLS, syslog…).

4.2 Fases

Fase	¿Sandbox?	Qué hace
fetch	No (red)	Clona al commit / baja el tarball y verifica sha256; vendorea Cargo/Go
patch	Sí	Aplica source.patches
configure	Sí	Heurística de build system: autotools / cmake / meson / cargo / make plano
compile	Sí	Compila al target/link de la receta
install	Sí	make install DESTDIR=/out o equivalente
seal	No	Hashea /out y lo deposita en el store

Materialización de build-deps: cada deps.build se construye recursivamente y su artefacto se apila como capa --overlay-src BAJO el rootfs del sandbox, dejando sus usr/{include,lib, lib/pkgconfig} en /usr. Así pkgconf y zig cc los encuentran sin plumbing de flags, y las recetas sin deps quedan byte-iguales (baseline intacto).

4.3 Poliglotismo

• C/C++: zig cc por defecto (ADR 0003: un binario = compilador + musl + headers, hermético, cross). Escotilla compiler = "gcc" para gcc-ismos (hoy ~16 recetas).
• Cargo: triple traducido (x86_64-linux-musl → x86_64-unknown-linux-musl), wrapper zig cc como CARGO_TARGET_<triple>_LINKER (cargo no acepta linker de dos palabras), --release --locked --offline con vendor/ obligatorio. link = "dynamic" añade -C target-feature=-crt-static (necesario para dlopen de Vulkan/Wayland).
• Go: 362 recetas (medido); el go mod vendor ocurre en el host, antes del sandbox.

4.4 harkaq — la jaula (SDD 16)

Tesis: bwrap da hermeticidad respecto del host, pero monta un rootfs Alpine entero como capa base ⇒ política ⊋ clausura: una receta puede usar cualquier header o binario de Alpine sin declararlo y el build pasa en verde. harkaq cierra esa brecha: la clausura de deps declaradas ES la política (Landlock + seccomp), y el producto es evidencia negativa: hermético ⟺ política = clausura ∧ denegaciones = ∅.

Decisiones cerradas: D1 política derivada, no escrita · D2 evidencia negativa (por eso es barata) · D3 cero quieting (las denegaciones SON el producto; ABI 10 trae ADD_RULE_QUIET y se decide deliberadamente no usarlo) · D4 seccomp obligatorio, no opcional · D7 fallo cerrado y honesto sobre el ABI (kernel sin Landlock ⇒ build marcado sin evidencia, nunca fingir) · D9 el canario deliberado: denials=[] no se cree, se gana (se antepone un acceso que DEBE ser denegado; si no aparece, el lector está roto).

Estado: Fase 0 y Fase 1 cerradas (zlib real: configure→Hermetico, compile→Impuro por /usr/bin/make no declarado); wiring en takana-build/src/harkaq.rs detrás de HARKAQ=1 e inerte sin él (requisito duro: 700+ artefactos sellados no pueden cambiar de hash por encender un diagnóstico). Barrido en granja: 0 irreducibles ⇒ la meta de <5% de deuda se cumple. Sutileza medida: lo que DAC ya bloquea es invisible a Landlock (el hook no llega a correr) — inocuo para el veredicto, trampa para escribir tests.

Regla operativa aprendida: el worker MIDE, el hub CLASIFICA (un store parcial infla la métrica).

---

5. El bucle agéntico (SDD 07, 08)

5.1 Dos canales

• /run/init.control — FIFO de control humano, texto crudo (echo "restart network" > …).
• /run/agent.sock — socket de agente: JSON-líneas, handshake Hello/Welcome, auth por SO_PEERCRED, capacidades leídas de /etc/hammer/agent-caps.toml (default + [[rule]] por uid/gid, primera que casa gana).

Comandos: Compile, Inject, Query, Init. Eventos: BuildReady, BuildFailed (con log_tail real de 50 líneas del compilador), Injected, QueryResult, InitAck, Modified, Crashed, Error.

Capacidades mínimas: por defecto un agente sólo obtiene query. compile, inject (a overlay) e inject-real (al FHS) se conceden por separado; inject-real exige confirmación humana por política.

5.2 El bucle

intención NL → PLAN (.swm) → BUILD (lab) → TRY (overlay) → VERIFY (tests + evidence)
             → PROPOSE (diff + evidencia) → HUMANO decide commit/discard

takana ai <intent> --catalog F | --llm [--repair-max-attempts N]. El traductor está detrás del trait IntentTranslator: MockTranslator (catálogo YAML intent→.swm, para CI byte-a-byte) y ClaudeTranslator (feature llm-claude, ureq+rustls). Orchestrator::run_with_repair drena eventos del bus tras cada apply; si llega Crashed, formatea una intención nueva y reentra hasta max_attempts, y el Proposal final lleva la repair_chain completa.

Mini-lenguaje de consulta (takana query kind:value): bin, file, pin, service, depends — con parser ELF64 mínimo para extraer DT_NEEDED.

---

6. Modelo de confianza (SDD 09)

fuente pública (repo@commit fijado) + patch declarado
        → build determinista en TU lab local → artifact_hash
        → ¿coincide con el expected_hash del autor?
             sí → obtuviste su binario sin descargarlo
             no → algo difiere (pin, patch, toolchain); takana dice qué

La firma Ed25519 cubre autoría e integridad, no autoriza promover: apply siempre reproduce y compara, firme o no. TrustStore local en /var/lib/hammer/trust/*.ed25519.pub; estados trusted/unknown-key/bad-sig/unsigned. El log de transparencia es opt-in y su embrión ya existe: bootstrap.json (SDD 11 §4).

Requisitos prácticos de reproducibilidad: toolchain fijado (ya en el hash), commits fijados, sandbox hermético, y eliminación activa de no-determinismo. Cuando un build no reproduce es un bug a corregir, no una excepción a tolerar.

---

7. Bootstrap y auto-alojamiento (SDD 11, 12; ADR 0007, 0008) — CERRADO

host (sólo kernel + semilla pinned)
 └─ Stage 0: toolchain semilla (zig) ingerido al store, sha256 fijado   ✅
 └─ Stage 1: userland mínimo cross-compilado (musl, busybox, hammerd, arje-zero)  ✅
 └─ Stage 2: rebuild NATIVO dentro del rootfs Stage 1 y comparación de of_tree     ✅

Hitos verificados:

• Stage 1 bootea en QEMU con arje-zero como PID 1 (init propio, del monorepo hermano tawasuyu) leyendo su seed card /ente/seed.card.json y supervisando hammerd + getty. El CRASHED real que la Fase 5 había diferido está demostrado: kill hammerd → arje detecta Killed(SIGTERM), aplica backoff y re-encarna.
• Stage 2 ✓ REPRODUCIBLE host↔VM: of_tree(stage1') == of_tree(stage1).
• Auto-alojamiento puro (variante b) CERRADO: el toolchain del builder lo construye takana desde fuente. Los 6 swaps (make, busybox, coreutils, bwrap, linux-headers, rust) corrieron juntos in-VM dando ✓ REPRODUCIBLE (of_tree = 7fa6cb4e…). La cadena de Rust es purista: mrustc → rustc 1.90.0 → 1.91.0 → 1.91.1 con x.py real, reusando un LLVM 20.1.8 externo.
• Kernel from-source CERRADO: Linux 6.16.12 construido por takana bootea la VM del selfhost-verify y reproduce bit a bit. flex, bison, openssl, elfutils (sólo libelf, para objtool) de-Alpinizados como build-deps del kernel.

Los dos no-determinismos que hubo que cazar (valen como lección general):

1. codegen-units=1 NO bastaba: el backend paralelo de rustc/LLVM (ThinLTO) divergía ~62 KB en arje-zero a >1 CPU. Fix: CARGO_BUILD_JOBS=1 serializa el jobserver ⇒ reproducible e independiente del nº de CPUs.
2. El baseline "bueno" anterior (0039b2b9…) era un build paralelo no fiable. Dos números iguales de un fallo son señal, no coincidencia; y un baseline no verificado es una foto vieja con aspecto de dato fresco.

---

8. Release engineering (SDD 13) — imágenes, instalador, mirror, upgrades

• E1 imagen auto-booteable (GRUB BIOS i386-pc, instalado en userspace sin root con grub-mkimage + grub-bios-setup sobre el fichero imagen). Layout GPT: BIOS-boot / / / /store / /var/lib/hammer.
• E2 instalador a disco físico: takana-install <dev> corre dentro del live como root real (MBR, ext2 montable como ext4, GRUB por dos dd). Autoinstalador: copia la propia raíz del live.
• E3 mirror del store (takana mirror push|pull|status): CAS replicado; el receptor recomputa of_tree y exige que case antes de sellar ⇒ una transferencia corrupta se rechaza.
• E4 upgrades con generaciones: apply in-place fichero-a-fichero (escritura a temporal + rename), current como commit-point, backup/ con los bytes previos, rollback exacto, prune, y pending.json escrito ANTES de proyectar para que recover complete (roll-forward) o deshaga (roll-back). hammer-recover (binario estático) lo hace al arranque, antes de encarnar a arje-zero, y nunca aborta el boot.
• E5 ISO/medio live: híbrido BIOS+UEFI (dos El Torito), initramfs = product-rootfs cpio.gz, todo desde RAM. Dogfooding: el host no traía xorriso ni mtools ⇒ los construye takana.
• Arranque soberano EFI-stub sin GRUB (ADR 0010), con cero parpadeo validado por captura de framebuffer.

---

9. Arranque por grafo (ADR 0010) — la frontera con tawasuyu/mirada

El menú de arranque no es una lista de kernels: es la navegación del grafo de estados del sistema. takana publica /run/hammer/boot-graph.json (nodos = generaciones/snapshots/base/recovery, identificados por BLAKE3, con parents, bootable, label); mirada (compositor Wayland de tawasuyu) lo dibuja sobre KMS y escribe la elección en /run/hammer/boot-select; arje-zero (PID 1) corre takana boot activate --from-select incondicionalmente en su secuencia de apagado — /run es tmpfs, así que la selección se aplica en el apagado o no se aplica nunca.

Invariante de UX compartido: cero parpadeo de DRM desde la firmware hasta el escritorio (mirada sostiene el DRM master y nunca re-modesetea; por eso mirada real nunca sale y el subcomando takana boot menu es sólo harness de dev).

---

10. El armador de kernel (SDD 22) — implementado

Verbo takana kernel {stats, probe, bundles, closure, plan, diff-back, gate, hw}.

Los dos hechos que ordenan el diseño:

1. El config ES la identidad del artefacto (vive en la fase configure). A favor: un "config atestado por huella de hardware" sale casi gratis (es un ArtifactHash + una firma). En contra: la explosión combinatoria es aritmética visible en el disco ⇒ una perilla de la UI no es un parámetro de runtime, es una edición de receta, y kernel plan debe emitir una receta derivada.
2. La clausura por depends on NO cierra: select es el portillo. Kconfig tiene al menos tres tipos de arista (depends on hacia arriba, select hacia abajo y forzada, imply blanda) con semánticas incompatibles. Hay corpus de verdad-de-campo contra el que validar: el configure de linux.toml ya es un juego de bundles escrito a mano (-d WLAN -d WIRELESS -d CFG80211…) y ese kernel arranca.

Añadidos propios del SDD: bisección sin recompilar (kernel superset con lo bisecable como =m ⇒ 6 reinicios en vez de 6 rebuilds × 45 min) y gate de no-regresión por objetivo, no global (el kernel de QEMU apaga USB/HID a propósito; un gate global rechazaría una receta sana).

Probado de punta a punta el 2026-08-11: kernel a medida de gioser, bzImage 11,1 MB vs 14,5 (−23%). Y el lab está literalmente DENTRO del artefacto: Kconfig sondea el rustc del entorno y graba CONFIG_GCC_VERSION/CONFIG_RUSTC_VERSION en el .config.

---

11. Los escritorios (cuatro imágenes, todas desde fuente)

Frente	Estado	Notas clave
mirada	perfil 33/33 (medido)	Compositor Wayland propio (tawasuyu) + greeter, sobre mesa software o iris
KDE Plasma 6	perfil escritorio-kde 163/163 (medido)	Hidratado rebuild-free vía takana hydrate <hash> --into (install-reproduce no escala). ADR 0011
GNOME	perfil 124/127, 3 aparcadas por diseño (medido)	Keystone: el shell es una isla dinámica — gjs dlopenea .so reales ⇒ la introspección los exige. mutter→gnome-shell es HUB-ONLY estructural
COSMIC	perfil 89/90 (medido)	4º escritorio usable, 6 apps + panel/dock, portal cerrado (captura da PNG real). Barato: no hay torre de C debajo
wlr/sway	perfil escritorio-sway 129/129 (medido), arranca en QEMU	10 recetas en una noche: wlroots, sway, yambar, fuzzel, swaybg/lock/idle, grim, slurp, wl-clipboard

Stack gráfico (SDD 14): Mesa 24.0.9 iris-only, sin LLVM y sin Vulkan. El pin es duro: desde 24.1 iris exige intel-clc ⇒ libclc + clang/LLVM. Debajo: libdrm, wayland (+ el parche wayland-scanner-dup2-output — bajo musl dinámico freopen(@OUTPUT@) trunca el header por la copy-relocation de stdout), wayland-protocols, seatd, libinput/libevdev/mtdev/libudev-zero, libxkbcommon, pixman.

La lección transversal de este bloque, y probablemente la más importante del proyecto:

Sellado ≠ arranca. El perfil escritorio-sway cerró 121/121, falta 0 — y entre eso y una pantalla con algo dibujado hubo seis muros y ocho ciclos de imagen: PATH vacío, libz.so.1 ausente del rootfs, un backend de libseat que nuestra receta no construye, /run de sólo lectura, los datos XKB ausentes, y falta de tipografías. Ninguno era una dependencia de build, así que ninguno podía aparecer en el grafo. Y el método: el veredicto es contar colores del PPM, no leer el log — hubo un arranque con todo verde en el log y la captura 100 % negra.

---

12. Infraestructura operativa (lo que no está en los SDD pero gobierna el día a día)

12.1 Topología

• Hub principal: laptop del autor + un segundo hub gioser.net (server Hetzner protegido, sin backup, mismo proyecto hcloud que la granja). El store vive en un volumen dedicado (bind-mount de store, work/sources, work/repos, CARGO_HOME).
• Granja efímera: workers hcloud on-demand (farm-up / farm-run / farm-down, baseline €0), arrancados desde un snapshot golden que trae el toolchain + el store horneados ⇒ cache-hit instantáneo. El worker es compute puro y sin secretos (ni firma ni gitea). Lleva un dead-man que lo borra (no lo apaga — apagado seguiría facturando) tras 1 h idle.
• Latido: un cron cada 30 min cosecha el worker, siembra recetas y regenera el grafo. Los commits estado: cosecha granja <ts> del historial son ese latido.
• Respaldo: Storage Box BX11 (1 TiB), interrumpible y continuable; sube primero el cerebro (estado + repo) y después el store.
• Espejo: origin empuja a gitea y a un espejo privado de GitHub.

12.2 El khipu y la yupana — la metodología de medición

Distinción explícita y arquitectónica, no adorno:

• docs/state/build-state*.json = el KHIPU: el registro firme y versionado (nudos = recetas, cuerdas = deps). Fuente única de verdad de QUÉ hay y QUÉ falta. Se regenera (scripts/build-state.py); un generado que no se regenera es una foto vieja con aspecto de dato fresco (error real: KDE reportaba 162/162 cuando estaba en 76/162).
• scripts/yupana.py = la YUPANA: el motor que reckona sobre el khipu. Es la puerta única de la metodología. Verbos: radio <receta> (¿a quién rompo si toco esto?), perfiles, duplicados, keystones, preflight, estado, objetivo, frontera, triaje, drenar.

La regla que la justifica: qué nodos puntúo es una decisión de vista; quién me consume es un hecho y nunca depende de la vista. Nació de un fallo real: un cambio a libdrm invalidó 118 recetas KDE, y el radio medido sólo contra recipes/*.toml dio 8. Las dependencias inversas se calculan SIEMPRE sobre todas las colas.

Resolución sibling-first: una dep libdrm desde incoming-kde resuelve a incoming-kde/libdrm si existe, y si no cae a corpus/libdrm — igual que el sandbox al apilar capas. Por eso los nodos se identifican por par (cola, nombre), no por nombre.

Otros órganos: targets.py (perfiles → lista), drenar.py (orden de masticado en ondas), triaje.py, seed-graph.py --frontera, affected.py (CVE por grafo), why-differs.py, verificar-repro.sh, store-gc.sh, licencias*.sh, fuentes/mirror-* (ADR 0013).

12.3 targets.toml — el manifiesto de OBJETIVO

build-state.json es el grafo de lo que EXISTE; targets.toml es lo que la distro debe tener. La inversión clave: paquetes lista sólo las raíces (lo que un usuario pide por nombre); la clausura la calcula el grafo. Siete perfiles: base, cli, escritorio-mirada, escritorio-kde, escritorio-gnome, escritorio-cosmic, escritorio-sway. Un perfil = una imagen enviable; hereda compone; cola dice en qué árbol viven sus raíces.

12.4 ADR 0013 — mirror de fuentes (obligación GPL, y sale barato)

La URL no entra en hash_inputs; sólo el sha256/commit ⇒ los mirrors son gratis. Cerrado: tarballs por sha256 (1,7 G) + git por bundle shallow (570/571, 2,3 G). Detalles pagados: 4 pines no son commits sino objetos tag (hay que pelar con ^{commit}); github.com es el 64 % del corpus. Regla dura: nunca cambiar el sha256 para tapar un 404. Vigía activo: fuentes-vigia.json → 1172 fuentes, 1172 vivas, 0 muertas (medido).

---

13. Estado real medido (2026-08-28)

13.1 Corpus

Métrica	Valor (medido)
Recetas .toml activas	1172 (+25 aparcadas en */.deferred)
— corpus (recipes/)	787
— incoming-kde / -gnome / -cosmic / -gnome-onda2 / -wlr / -onda1	205 / 90 / 47 / 22 / 15 / 6
Parches .patch en el árbol de recetas	123
Recetas con campo license	1096 / 1197 (92 %)
Recetas con compiler = "gcc"	36 (16 en el corpus, 20 en las colas)
Recetas con strip_debug (campaña SDD 23)	35, todas en el corpus
Recetas que pinean zig_version = "0.13.0"	84
Entradas en el store local	1654 (55 G en este disco; el store real vive en el volumen)
Fuentes vivas (vigía)	1172 / 1172, 0 muertas

13.2 Grafo de estado, por vista

Vista	nodos	sellados	deuda
corpus	787	711	75
KDE (--kde)	978	899	74 (+4 wanted)
GNOME	861	783	74 (+4 never)
COSMIC	833	757	75
wlr	801	726	74

Deuda del corpus por clase: go 37 · rust 26 · c 12 · gui 1.

Perfiles (medido): base 52/52 · cli 75/75 · escritorio-mirada 33/33 · escritorio-kde 163/163 · escritorio-sway 129/129 · escritorio-cosmic 89/90 · escritorio-gnome 124/127.

13.3 Lectura de la deuda actual (importante para no malinterpretar los SDD 19/20)

Los SDD 19/20 (2026-08-07) hablan de «12 recetas en deuda». Hoy el corpus marca 75, y no es una regresión de calidad: la lista de nombres en deuda va alfabéticamente desde llimphi-counter/mise hasta zola — es la cola pendiente de la campaña de reconstrucción del corpus en serie (scripts/reconstruir-corpus.sh, reanudable, alfabética), disparada por los dos eventos que movieron el ArtifactHash de todo el catálogo a la vez:

1. El lab entró en hash_inputs (2026-08-10, §3.3).
2. El split de debug (SDD 23, strip_debug), que cambia la fase install.

Y el diagnóstico de «las 12» originales fue desmontado después: 6 estaban SUPERADAS por la cadena dinámica de GNOME, 1 cerrada (wlr-randr: le faltaban python3 —meson es un script de Python— y libffi, que exige wayland-client.pc en su Requires), 1 es frente propio (elfutils-libdw, ya cerrado: dwarves construye) y 3 son HUB-ONLY estructural (fuente por SSH a gitea privado; el worker es sin secretos por diseño). El hallazgo de fondo fue de encolado, no técnico: recipes/ (el corpus) no estaba en la lista QUEUES del bucle del worker — nadie las estaba intentando.

---

14. Deuda abierta y problemas sin resolver

14.1 ADR 0012 — la carrera del árbol de fuentes (PENDIENTE, sin decidir)

fetch nombra el árbol de forma determinista y sin componente por-constructor: work/sources/<nombre>-<sha16>. Dos builds de la misma dep resuelven al MISMO directorio; uno hace remove_dir_all mientras el otro corre tar -x y el árbol queda roto para siempre.

El árbol cumple dos papeles que se contradicen bajo concurrencia: caché direccionada por contenido y workspace mutable de build (patches, cargo vendor, go mod vendor — minutos y decenas de GB). Por eso un lock sólo en la extracción parece correcto y NO lo es: un segundo proceso puede borrar un árbol que un bwrap está usando para compilar.

Medido a escala: al invalidar libdrm, ~93 de 205 recetas KDE murieron con /src/.zwrap/cc is not a full path to an existing compiler tool — el wrapper de zig que la receta deja EN EL ÁRBOL, barrido por el fetch concurrente de otra receta.

Mitigación vigente (no solución): flock work/.farm-build.lock alrededor de todo takana build, tomado también por farm-worker-loop.sh y campana-deuda.sh, y JOBS=1 en el worker. Opciones sobre la mesa, ninguna elegida: (A) lock por árbol sostenido durante todo el build —correcto pero serializa el diamante que converge en qtbase/kcoreaddons—, (B) árbol privado por constructor, (C) caché inmutable + copia.

14.2 No-determinismo en .debug_* (SDD 23)

92 paquetes con no-determinismo probable. La causa medida no son rutas del host sino rutas internas al árbol de build que varían entre corridas (/src/output/meson-private). Verificado con takana why-differs: binutils y wl-clipboard reproducen; appstream y bison divergen, y la divergencia vive ENTERA en secciones .debug_* (el código ejecutable es idéntico).

La buena noticia estructural: las dos mitades del plan son el mismo trabajo — separar el debug hace que el artefacto principal reproduzca, sin tocar -ffile-prefix-map en ~720 recetas. Y el tamaño: ~60 % del artefacto es información de depuración (el «79 %» que se citaba medía el contenido binario, no el artefacto) ⇒ el espejo público baja de ~126 G a ~51 G.

Estado de la campaña (medido): sólo 35 recetas declaran strip_debug, todas en el corpus. Es decir: el mecanismo está implementado y el plan escrito, pero el barrido está en su arranque — y cada tanda re-hashea lo que toca, así que compite por la misma granja que la reconstrucción del corpus (§13.3).

14.3 Otros frentes abiertos

• 36 recetas con compiler = "gcc" (medido: 16 en el corpus + 20 en las colas de escritorio; contadas parseando TOML, porque grep cuenta comentarios). Las 12 de Rust son un solo problema: falta el unwinder de libgcc (perilla LIBS=-lunwind ya identificada).
• Techo MSRV del sandbox = 1.96. La frontera son los *-sys con C++ — y es exactamente lo que bloquea Firefox. Antes del navegador hay que subir el techo.
• *-sys que piden libs C sin [deps]: unable to find static system library 'lzma'/'bz2' en recetas Cargo. Arreglo por receta (xz, bzip2, sqlite), nunca engordar el rootfs, y nunca en bloque: hay ~220 recetas Cargo sin deps y re-hashearlas invalidaría las selladas.
• Multi-init: los inits del catálogo (openrc, etc.) compiten con arje-zero, no se apilan.
• link=static es a veces mentira: cuatro causas distintas (libtool se come el -static; el Makefile lo pisa; link es INERTE en Go; la receta Cargo pisa el lab y pierde crt-static). Auditado: 0/680 mienten hoy, pero el audit sobre-reporta si no se re-sella antes.
• Licencias: 1096/1197 declaran; faltan ~101 y hay que desambiguar SPDX obsoletos (GPL-3.0 no dice si -only u -or-later). Regla dura: no se rellena a ojo — declarar mal es peor que dejar vacío, porque convierte un hueco visible en una afirmación falsa. El cierre definitivo es capturar la licencia en la fase de fetch, donde el dato pasa gratis.
• Falta para publicar (SDD 19/20/21): espejo de fuentes servido, clave raíz fuera de línea (lo único no delegable a un agente), imagen validada en metal con pantalla, upgrade N→N+1 con rollback probado, cups y bluez, documentación mínima y canal de reportes.
• Aplicaciones gráficas de terceros: cero. Barato: imv, zathura, mpv, gestor de archivos. Caro: LibreOffice. El más caro del catálogo: un navegador.

14.4 Modos de fallo estructurales que este proyecto descubrió (y que valen como principio)

1. Un artefacto VACÍO es un cache-hit. takana build miraba presencia del directorio, no contenido ⇒ sellaba sin construir y salía OK. Siete vacíos se propagaron de respaldo → manifiesto → grafo → store → build: en cada eslabón el vacío se lee como presencia. Regla: un ausente falla ruidosamente; un vacío llega hasta el final diciendo que todo fue bien.
2. El cache-hit congela regresiones. «No re-hashea nada sellado» ≠ «es seguro»: una regla del wrapper llevaba meses rompiendo make sin que se viera, porque el artefacto viejo se servía por caché. Al reconstruir: exit 139 en medio corpus. ⇒ tras tocar el harness, reconstruir a propósito una receta de cada tipo.
3. Con flota efímera y sync unidireccional, un escritorio puede dejar de ser reconstruible-desde-el-store sin que ningún indicador lo diga. Pasó con KDE: los workers donde vivían esos artefactos ya no existen, el sustrato cambió, las sombras se re-hashearon y nadie las reconstruyó. El grafo seguía diciendo 162/162 en un JSON generado semanas antes.
4. grep no es una medición en este repo. Contó comentarios en el conteo de licencias (grep -l license → 5 falsos positivos), contó IO_URING en un comentario del kernel, y contó .rela.debug_* en la regla del .a no-PIC (readelf -r | grep R_X86_64_32 miente si no se excluye debug). El veredicto se obtiene reconstruyendo y comparando, no buscando cadenas.
5. .dmerge retiene lo que borrás del store (hardlinkea los artefactos) ⇒ podar el store no libera disco mientras la caché los referencie. Medir con st_nlink==1, nunca con du (suma los hardlinks otra vez).

---

15. La frontera (SDD 15, 17, 18) — lo diseñado pero no cerrado

15.1 SDD 15 — proof-carrying, cómputo como dato, código por contenido

• H1 — Proof-carrying recipes ✅: el .swm lleva un bloque evidence ({kind, cmd, expected}, kind ∈ {cmd-exit, proptest, contract, kani}); takana swm-verify --evidence corre cada ítem dentro del sandbox reproducible. La evidencia corre del lado del BUILD (separación PROPONE/CONSTRUYE: takana-agent no depende de takana-build); Event::BuildReady lleva el EvidenceVerdict y el Orchestrator aborta antes de hidratar si falla. Frontera honesta declarada: garantiza que lo declarado pasa, no que lo declarado basta.
• H2 — Memoización de ejecución ✅ (en wawa-memo, repo hermano): si el wasm es determinista, blake3(módulo) + blake3(entrada) + E → blake3(salida) es una función pura y su caché es un LwwMap monótono compartible por anti-entropy. E es un hash-de-entorno que pinea wasmi/features/fuel/mem/ABI. Único vector residual acotado: payload de NaN vía reinterpret.
• H3 — Código por contenido estilo Unison ✅ (subconjunto): Base content-addressed de funciones wasm — identidad = blake3(bytecode), nombres como metadata separada, actualizar no rompe (v1 y v2 coexisten), composición por hash. ADR 0009 decide NO reescribir la unidad de compilación; el puente barato es procedencia por-símbolo como metadata.
• H4 — Configuraciones compartidas ✅: el eje nuevo son los slots. Una modificación reclama (claim: slot→Id) y requiere (requires: slot→Id). Compatible queda definido duro: requisitos resueltos + reclamos disjuntos. Dos casos que el modelo trata distinto: logo (dos configs escriben la misma superficie ⇒ colisión = elección) y wayland (dependencia que no resuelve ⇒ rechazo). Subido a la receta real ([slots], fuera de hash_inputs) y a la InstalledDb (system_state() → slot → hash). CLI: takana compat.

La ambición declarada al final del SDD 15: config = paquete = función = proceso, todos el mismo tipo de objeto direccionado por el mismo hash.

15.2 SDD 17 — los diez cierres de frontera, priorizados

Tesis: los tres invariantes ya pagados —bit-reproducibilidad, direccionamiento por contenido y clausura-como-política— hacen casi gratis para takana lo que a otros les cuesta. La búsqueda correcta no es «qué frontera agregar» sino «qué cae solo del invariante».

1. Consenso de reconstrucción — N builders independientes reproducen el mismo hash ⇒ el binario es confiable sin que nadie firme nada. Convierte la repro de QA en primitiva de distribución: cualquiera puede ser mirror, nadie puede envenenar el repo. Nix/Debian no pueden ofrecerlo.
2. why-differs (diffoscope propio) — implementado: nombra la causa (un MTIME en un gzip, la cabecera ar de un .a, qué sección ELF cambió, una ruta filtrada). Multiplicador de todo lo demás.
3. Política de runtime derivada del closure — fase 3 de harkaq. Con dos correcciones medidas: (a) la clausura de build no puede ser la política de runtime porque le sobra casi todo (un htop musl-estático bajo la jaula no tocó un solo fichero fuera de sí mismo; derivarla del build le habría concedido headers y compilador, firmados) ⇒ la política granular se MIDE corriendo el binario; (b) la lección casper: hay una clase —servicios del mundo— que no son paths y no caben en ninguna jaula por-fichero, y el build offline no la contiene ⇒ frontera (clases dns/tls-certs/random/locale-tz/syslog, bits de un u32 firmado de 36 bytes canónicos) + detalle (paths, Landlock, medidos).
4. CVE por grafo — takana affected CVE-X exacto + frontera mínima de rebuild + hydrate para repartir el parche rebuild-free. Donde Debian/Alpine aproximan por nombre-versión, takana responde exacto.
5. Sellar el arranque — verity + medida; el store CAS hace fs-verity casi gratis.
6. Matar el trusting-trust: DDC — con la cadena mrustc cerrada, takana es de los poquísimos que puede ejecutar Diverse Double-Compiling. Un fin de semana de granja, resultado publicable.
7. De-Alpinizar el rootfs del sandbox — canal impuro estructural mientras el sandbox se apoye en Alpine; harkaq lo mide.
8. takana oci — imágenes distroless bit-reproducibles desde un closure. Vector de adopción realista.
9. Updates diferenciales content-defined (chunking estilo casync sobre el store).
10. Bucle agéntico con juez mecánico — LA tesis AI-nativa: el catálogo se cultiva solo porque el juez es mecánico. Sin juez, las recetas de un LLM son deuda; con él, son cosecha. Ya demostrado a mano con zlib (Impuro→Hermetico en 3 fases, guiado sólo por harkaq).

Qué NO priorizar (dicho explícitamente): solver SAT de versiones (el grafo es curado), multi-arch (esperar demanda), config declarativa estilo NixOS (cancha ajena).

15.3 SDD 18 — wawafs: el store como filesystem del sistema vivo

Diseño aceptado, sin implementar. Bajar el checkout de userspace al kernel con la pila composefs (CAS + erofs + overlayfs + fs-verity, todo mainline): no hay que escribir un filesystem. Capas: proceso → VFS (rutas FHS reales, sin pueblo fantasma) → composefs mount → manifest erofs por clausura (KB–MB, cero datos) → CAS de objetos → fs-verity opcional → ext4.

Propiedades que caen solas: dedup de disco y de page cache, activar/rollback O(metadata), inmutabilidad estructural, y bit-repro en runtime (el kernel verifica el Merkle en cada lectura; un bit podrido = EIO, no un binario silenciosamente distinto).

Identidad: dos granos, un mapa. blake3 sigue siendo la identidad (recetas, sellado, grafo); el digest fs-verity (sha256) es el enforcement. Misma jugada que ADR 0009.

ADR 0005 (hardlinks) sigue vigente para el laptop de desarrollo; wawafs es el modo despliegue (ro). El corte cae donde el workload cambia de naturaleza: se escribe una vez al sellar, se lee mil veces al vivir. Prototipo medido (2026-07-17): hydrate 28 ms vs mkcomposefs 507 ms sobre un rootfs de 262 MB; manifiesto .cfs de 136 KB firmables. Hallazgo: con hardlinks, un write con privilegios a través del árbol hidratado corrompe el store (comparten inode); con composefs es imposible por construcción. Precondición: el kernel propio trae OVERLAY_FS+REDIRECT_DIR+METACOPY pero falta EROFS_FS y FS_VERITY ⇒ re-sellado de kernel.

---

16. Los ADR, con su estado

#	Decisión	Estado
0001	Rust para el tooling y los daemons	aceptada
0002	Validar sobre Alpine antes de la distro propia	aceptada
0003	zig cc como compilador por defecto del lab	aceptada
0004	No escribir nuestro propio Nix	aceptada
0005	Hidratación por hardlinks	aceptada (convive con wawafs como backend futuro)
0006	Commits fijados, no HEAD vivo	aceptada
0007	arje como init propio del track posterior	propuesta (implementada de facto)
0008	Bootstrap en 3 stages, zig como semilla	aceptada
0009	Código direccionado por contenido (Unison): registrar la visión, no reescribir	propuesta / design-doc
0010	Arranque por grafo: el menú de boot como navegación del grafo	aceptado; lado takana 1–5 ✅
0011	Etapa Escritorio: campaña KDE Plasma 6	aceptado; gates H-Qt y H-QML pasados
0012	El árbol de fuentes es caché y workspace a la vez	PENDIENTE, sin decidir
0013	Mirror de fuentes: la URL es transporte, el sha256 es la identidad	ACEPTADO, implementado

---

17. Superficie del CLI (takana)

build · hash [--check] · why-differs · attest · hydrate
try · commit · discard · status · journal
apply · swm-verify [--evidence] · swm-sign · keygen · export
pack · install · uninstall · installed · compat · repo {list,sign,verify}
import-nix · import-alpine · pin
ai [--catalog|--llm] [--repair-max-attempts] · ctl · query
bootstrap {stage0,stage1,stage2,builder,all,manifest}
mirror {push,pull,status}
upgrade {apply,rollback,recover,status,prune}
boot {graph,activate,menu}
kernel {stats,probe,bundles,closure,plan,diff-back,gate,hw}

Daemon: hammerd [--journal DIR] [--agent-caps FILE].

---

18. Reglas del repo (CLAUDE.md) — no son estilo, son seguridad

1. Todo takana build va envuelto en flock work/.farm-build.lock. Por el ADR 0012. Para una tanda, tomar el lock una sola vez, no por receta. El lock está fuera de takana build a propósito: los scripts de granja lo toman por fuera y takana se bloquearía contra ellos.
2. Nunca git add -A. Varios agentes trabajan el repo a la vez; un add -A arrastra ficheros a medias de otro. Commits granulares, en español, directo sobre main, y git push tras cada unidad de trabajo.
3. Antes de dar un artefacto por presente, mirá que tenga contenido. (Ver §14.4.1.)

---

19. Vocabulario del proyecto (para leer commits y docs sin perderse)

Término	Qué es
el lab / el sótano	El laboratorio de build hermético
sellar	Depositar un artefacto en el store bajo su hash
hidratar	Proyectar un artefacto del store al FHS
la granja	La flota efímera de workers hcloud
el hub	La máquina con secretos (laptop o gioser); firma, gitea, clasifica
el latido	El cron */30 que cosecha, siembra y regenera el grafo
cola / queue	Un árbol de recetas: corpus = recipes/; el resto recipes/incoming-<x>/
sombra	Una receta homónima en otra cola que gana por sibling-first
deuda	Nodo del grafo sin artefacto en su hash vigente
drenar	Construir la deuda en ondas topológicas
frontera	Lo que upstream pide y no tenemos
keystone	Nodo en deuda que gatea el máximo trabajo bloqueado
radio	Cuántos nodos rompo si toco una receta
superado / huérfano	Artefacto con ejemplar mejor (podable gratis) / ejemplar único
de-Alpinizar	Quitarle a una receta la dependencia implícita del rootfs Alpine
harkaq	La jaula (Landlock+seccomp) que verifica que lo declarado basta
yupana / khipu	El motor de cálculo sobre el estado / el registro firme del estado
arje / arje-zero	El init propio (PID 1) del monorepo hermano tawasuyu
mirada	El compositor Wayland de tawasuyu que dibuja el menú de arranque
wawa / wawafs	El runtime wasm de tawasuyu / el frente de store-como-FS

---

20. Dónde hay hueco para SDDs nuevos

Esto es lectura del autor de este informe, no doctrina del repo. Los huecos donde un SDD tendría tracción real, con la razón por la que hoy no existe uno:

1. ADR 0012 resuelto → SDD del modelo de árbol de fuentes. Es la única decisión estructural marcada PENDIENTE, bloquea el paralelismo del worker (JOBS=1) y ya rompió una campaña entera. Cualquier propuesta debe cubrir extracción + build, no sólo la extracción, y decir qué pasa con cargo vendor (minutos, decenas de GB) y con el diamante que converge en qtbase.
2. SDD del split de debug terminado (SDD 23 está a medias): qué se hace con el paquete -debug en sí, cómo viaja por el repo .swm, y si -ffile-prefix-map entra o no. Decide ~96 G de disco y el tamaño del espejo público.
3. SDD de gestión de claves y cadena de release. Hoy hay firma de índice; falta clave raíz offline, rotación, procedimiento de compromiso. Es bloqueante para publicar y el propio SDD 21 lo marca como lo único no delegable a un agente.
4. SDD de política de runtime (cierre §3 de SDD 17): el diseño de dos niveles ya está medido —frontera como bits de un u32 firmado, detalle medido corriendo el binario— pero no hay documento que lo fije ni herramienta que lo emita end-to-end.
5. SDD de consenso de reconstrucción (cierre §1 de SDD 17): el más diferenciador y el que convierte la reproducibilidad de QA en primitiva de distribución. Las piezas (granja, bootstrap.json, fork-proof, umbral) existen; falta el protocolo.
6. SDD de validación de imagen: de «cierra en el grafo» a «arranca». La lección sellado ≠ arranca costó seis muros y ocho ciclos y no tiene documento: hoy vive como anécdota en el §II.1 del SDD 20. Un harness reproducible (contar colores del PPM, comparar NEEDED del ELF contra el rootfs, verificar datos XKB/tipografías//run rw) evitaría pagarlo una vez por perfil.
7. SDD del catálogo de aplicaciones gráficas, con el techo MSRV como precondición explícita: hoy el navegador está presupuestado como frente propio pero sin plan escrito, y el orden correcto (subir el techo → *-sys con C++ → Firefox) sólo aparece como nota en el SDD 21.
8. SDD de wawafs F0–F3 ya existe (SDD 18) pero está sin implementar y sin gate ejecutado; su F0 es barato (spike en QEMU con composefs de paquete) y decide si el frente existe.
9. SDD de la fase de fetch como capturadora de metadatos (licencia, y por extensión SBOM): el propio SDD 20 identifica que ahí el dato «pasa gratis», y cerraría la deuda de licencias para siempre en vez de por barrido.

---

21. Cómo leer el repo (mapa de ficheros)

docs/00..23-*.md        los SDD (00 visión … 23 re-hasheo)
docs/adr/               las 13 decisiones
docs/runbooks/          operativos: stage1-vm-boot, self-hosting-toolchain, kde/gnome/cosmic-desktop,
                        armador-de-kernel, harkaq-*
docs/state/             build-state*.json (el khipu), targets.toml (el objetivo), drenaje.json,
                        lab-toolchain.lock, kernel-bundles.toml, keystones.json, fuentes-vigia.json
docs/evidencia/         capturas PNG que sostienen las afirmaciones de arranque
crates/                 los 12 crates del workspace
recipes/                787 recetas del corpus + colas incoming-{kde,gnome,cosmic,wlr,…}
scripts/                yupana.py (puerta única), build-state.py, drenar.py, targets.py,
                        why-differs.py, store-gc.sh, licencias*.sh, verificar-repro.sh,
                        selfhost-verify.sh, reconstruir-corpus.sh, lab-image.sh,
                        farm/ (30 scripts de granja), harkaq/ (19), fuentes/ (6), rust-frontier/ (8)
store/                  el CAS (bind-mount al volumen dedicado)
work/                   sources/, repos/, locks, logs de campaña

Punto de entrada recomendado para un agente nuevo: CLAUDE.md → docs/00-vision.md → docs/01-architecture.md → docs/10-roadmap.md → docs/state/build-state.json (regenerándolo) → scripts/yupana.py radio <receta> antes de tocar nada compartido.