Sergio
897fad178a
La unidad 7 del SDD 26 (§6.2). Cuando una descarga TERMINA, la extensión `descargas@atuq.tawasuyu` le pasa al host la ruta, el nombre y de dónde salió; el host la ingiere a un CAS BLAKE3 y contesta el hash, el tamaño y **cuántas veces se bajó ese mismo contenido**. El mismo contenido con otro nombre es UN objeto y dos nombres, y el navegador lo dice — que es exactamente lo que ningún navegador sabe hacer: para todos una descarga es un blob con nombre, y por eso la bajás dos veces y no te enterás. No es un almacén nuevo: es `arje-cas`, el mismo formato y el mismo hash que usan arje, takana y tejido. El `<hex>` del CAS ES el `expected_hash` de un `.swm`. ⚠ TRES DECISIONES QUE SALIERON DE MEDIR, NO DE DISEÑAR: 1. **La raíz del CAS de descargas no es la del sistema.** `arje_cas::gc` borra todo blob que no esté en el set `reachable` de su llamador, y el único que existe (`arje-brain`, `GcCas`) lo arma con la cadena de audit y las raíces vivas del grafo. Una descarga del usuario no está en ninguno: el primer GC se la llevaría, en silencio. Van a `<estado>/descargas-cas` — mismo formato (mover un objeto al CAS del sistema es un `rename`), fuera del alcance del GC de otro. El precio queda escrito: tejido sirve el CAS por defecto, así que compartir una descarga hoy exige apuntarlo ahí. 2. **El fichero del usuario no se toca**: se copia y se deja donde estaba. El guardián lo comprueba byte a byte. Borrar o mover lo que alguien acaba de bajar no es decisión de un navegador. 3. **La extensión observa, no intercepta.** Se entera cuando la descarga terminó. Meterse en el medio obligaría a decidir qué pasa si el CAS falla, y la respuesta correcta —que la descarga siga igual— es lo que se consigue no metiéndose. Y EL HALLAZGO QUE COSTÓ LA TARDE, que no es de esta unidad: **en `--headless` el navegador se cae con SIGSEGV en cuanto una descarga termina.** Se atribuyó con dos controles antes de tocar nada: --headless, con la extensión → baja el fichero, TERMINADA, Segmentation fault (139) --headless, SIN la extensión → baja el fichero, Segmentation fault (139) ← no es nuestro --headless, panel de descargas apagado → Segmentation fault (139) sway headless (compositor REAL) → baja, INGIERE al CAS, y no se cae ← no es del producto Sin el primer control esto se leía como «la extensión de descargas rompe el navegador» (perseguir un bug que no existe); sin el último, como «atuq no puede descargar» (reportar un bug de producto que tampoco existe). Por eso `scripts/test-atuq-descargas.py` corre sobre sway y no sobre `--headless`, y por eso lo dice en su cabecera: un arnés distinto al de los demás guardianes, sin explicación, es una invitación a «simplificarlo» de vuelta al que se cae. Queda en el §6.10.bis del SDD, que es donde vive lo que atuq NO puede hacer. El guardián baja de verdad (`Content-Disposition: attachment`, no una llamada a la API) dos veces dentro de un mismo compositor, y trae control negativo: con OTRO contenido la segunda vez exige `dedup=false` y dos objetos. Sin él, una sonda que dijera «ya lo tenías» siempre se vería idéntica a una que funciona. Del lado de tawasuyu (`ffa939c6`, pineado acá): `cas.ingest`/`cas.list` en el host y `arje-cas::almacenar_fichero_en` — ingesta en streaming, porque `store` toma `&[u8]` y una ISO de 4 GiB serían 4 GiB de `Vec`. 5 tests nuevos en arje-cas y 5 en puriy-costura. Y EL BUG QUE EL GUARDIÁN DESTAPÓ, que vale más que la función: **hay un host por PUERTO, no uno por perfil.** Con `sct` y `descargas` hablando hay dos procesos vivos a la vez, cada uno con su copia en memoria del estado, y cada uno escribía el fichero ENTERO al guardar: el de descargas borraba el registro TOFU de `sct` al salir, y el de `sct` revertía el índice de descargas. Los dos contestaban bien — el daño estaba sólo en el disco. Se vio porque el guardián lee el índice EN DISCO en vez de creerle a la respuesta: decía `veces=2` y el fichero decía 1. Arreglado en tawasuyu (`55b918e8`, pineado acá): cada proceso escribe sólo la parte que tocó, y el test que lo fija se comprobó ROMPIENDO el arreglo a propósito — porque la primera versión de ese test abría los hosts en secuencia y pasaba con el bug puesto.
Documentación de diseño de takana
Estos documentos son la fuente de verdad del diseño. El código los implementa; cuando haya discrepancia, o se corrige el código o se actualiza el SDD con un commit que explique por qué.
Software Design Documents (SDD)
| # | Documento | Qué cubre |
|---|---|---|
| 00 | Visión y filosofía | Por qué existe, qué problema resuelve, la actitud de ingeniería |
| 01 | Arquitectura general | El modelo de dos mundos, componentes, flujo de datos |
| 02 | El laboratorio de build | Sandbox, zig cc, recetas, CAS, grafo de dependencias |
| 03 | Hidratación y store | Store content-addressed, hardlinks a FHS, patchelf, rollback |
| 04 | Overlay de experimentación | overlayfs en caliente, try/commit/discard |
| 05 | Diario de mutaciones | fanotify, log append-only, config-sin-ser-declarativa |
| 06 | Formato .swm |
Manifiesto de mutación compartible, esquema, firma |
| 07 | Bus de init y de agente | /run/init.control, /run/agent.sock, protocolo |
| 08 | Integración de la IA | El bucle agéntico, seguridad, intención → .swm |
| 09 | Modelo de confianza | Reproducibilidad, verificar-no-confiar, log de transparencia |
| 10 | Roadmap | Fases, MVP, primer entregable |
| 11 | Bootstrap from-scratch | Track posterior: Stage 0/1/2, auto-alojamiento, semilla pinned |
| 12 | arje como init real del Stage 1 |
Contrato de runtime: seed card, hammerd supervisado, CRASHED real |
| 16 | harkaq: la jaula de takana | Landlock+seccomp sobre el bwrap actual; política = clausura; evidencia negativa de hermeticidad |
| 26 | atuq: el envoltorio Gecko |
Navegador propio como artefacto DERIVADO de firefox (no fork de fuente); la toolchain clang como puerta de PGO/LTO; qué se promete y qué no |
Runbooks (operativos)
| Runbook | Para qué |
|---|---|
| Validar Stage 1 booteando en QEMU | stage0→stage1→initramfs→QEMU; criterios de éxito y troubleshooting |
Architecture Decision Records (ADR)
Decisiones tomadas, con su contexto y consecuencias. Ver adr/.