Sergio
e5c47fd5b2
El diseño completo del hueco: qué declara el PAQUETE (`[[service]]`, hecho) y qué decide el PERFIL (si arranca, pendiente), que es la misma partición que systemd hace entre [Service] e [Install] y que `arje-absorb` respeta al absorber sólo lo habilitado. Deja escritas las dos cosas que cuestan caro si se descubren después: 1. El SDD 06 decía «el init (arje) lee ese árbol» de /etc/hammer/init.d/*.rule. Es FALSO: el único uso de INIT_RULES_DIR en el repo es escribirlo. Había TRES convenciones de dónde vive un servicio y ninguna se tocaba con las otras (más una cuarta en `query service:`). Canónicos son los de arje —genesis de la seed y cards.d/—; la mutación del .swm queda derogada o reapuntada, y la afirmación falsa queda marcada en su propio doc. 2. La trampa para el emisor: el sidecar .hammer/recipe.toml NO entra al ArtifactHash, así que el openssh ya sellado no lleva el bloque y, con el hash sin mover, NUNCA se reconstruye solo. Derivar la seed del sidecar hoy daría un producto SIN sshd, en silencio. Por eso product_seed_card() sigue usando la constante a propósito, y re-sellar es una unidad aparte CON control de reproducibilidad — openssh no está certificado como reproducible.
51 lines
3.7 KiB
Markdown
51 lines
3.7 KiB
Markdown
# 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](00-vision.md) | Por qué existe, qué problema resuelve, la actitud de ingeniería |
|
|
| 01 | [Arquitectura general](01-architecture.md) | El modelo de dos mundos, componentes, flujo de datos |
|
|
| 02 | [El laboratorio de build](02-build-lab.md) | Sandbox, `zig cc`, recetas, CAS, grafo de dependencias |
|
|
| 03 | [Hidratación y store](03-hydration.md) | Store content-addressed, hardlinks a FHS, patchelf, rollback |
|
|
| 04 | [Overlay de experimentación](04-overlay.md) | overlayfs en caliente, try/commit/discard |
|
|
| 05 | [Diario de mutaciones](05-journal.md) | fanotify, log append-only, config-sin-ser-declarativa |
|
|
| 06 | [Formato `.swm`](06-swm-format.md) | Manifiesto de mutación compartible, esquema, firma |
|
|
| 07 | [Bus de init y de agente](07-agent-bus.md) | `/run/init.control`, `/run/agent.sock`, protocolo |
|
|
| 08 | [Integración de la IA](08-ai-integration.md) | El bucle agéntico, seguridad, intención → `.swm` |
|
|
| 09 | [Modelo de confianza](09-trust-model.md) | Reproducibilidad, verificar-no-confiar, log de transparencia |
|
|
| 10 | [Roadmap](10-roadmap.md) | Fases, MVP, primer entregable |
|
|
| 11 | [Bootstrap from-scratch](11-bootstrap.md) | Track posterior: Stage 0/1/2, auto-alojamiento, semilla pinned |
|
|
| 12 | [`arje` como init real del Stage 1](12-init-real.md) | Contrato de runtime: seed card, hammerd supervisado, `CRASHED` real |
|
|
| 16 | [harkaq: la jaula de takana](16-harkaq-jaula.md) | Landlock+seccomp sobre el bwrap actual; política = clausura; evidencia negativa de hermeticidad |
|
|
| 26 | [`atuq`: el envoltorio Gecko](26-atuq-envoltorio-gecko.md) | 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 |
|
|
| 30 | [Los servicios que trae un paquete](30-servicios-de-paquete.md) | `[[service]]` en la receta → Card de arje; por qué `arje-absorb` no cubre una distro construida desde fuente; los tres árboles de servicios y cuál es el canónico |
|
|
|
|
### Runbooks (operativos)
|
|
|
|
| Runbook | Para qué |
|
|
|---|---|
|
|
| [Validar Stage 1 booteando en QEMU](runbooks/stage1-vm-boot.md) | `stage0`→`stage1`→initramfs→QEMU; criterios de éxito y troubleshooting |
|
|
|
|
## Architecture Decision Records (ADR)
|
|
|
|
Decisiones tomadas, con su contexto y consecuencias. Ver [`adr/`](adr/).
|
|
|
|
| # | Decisión |
|
|
|---|---|
|
|
| 0001 | [Rust para el tooling y daemons](adr/0001-rust-for-tooling.md) |
|
|
| 0002 | [Validar sobre Alpine antes de la distro propia](adr/0002-alpine-first.md) |
|
|
| 0003 | [`zig cc` como compilador por defecto del lab](adr/0003-zig-cc-builder.md) |
|
|
| 0004 | [No escribir nuestro propio Nix](adr/0004-no-custom-nix.md) |
|
|
| 0005 | [Hidratación por hardlinks](adr/0005-hardlink-hydration.md) |
|
|
| 0006 | [Commits fijados, no HEAD vivo](adr/0006-pinned-commits.md) |
|
|
| 0007 | [`arje` como init propio del track posterior](adr/0007-arje-como-init-propio.md) |
|
|
| 0008 | [Bootstrap en 3 stages, `zig` como semilla](adr/0008-bootstrap-stages.md) |
|
|
| 0009 | [Código direccionado por contenido (estilo Unison)](adr/0009-content-addressed-code.md) |
|
|
| 0010 | [Arranque por grafo: el menú de boot como navegación del grafo](adr/0010-arranque-grafo-mirada.md) |
|
|
| 0011 | [Etapa Escritorio: campaña KDE Plasma 6](adr/0011-escritorio-kde-plasma.md) |
|
|
| 0012 | [El árbol de fuentes es caché y workspace a la vez — **PENDIENTE, dilema abierto**](adr/0012-arbol-de-fuentes-compartido-vs-privado.md) |
|