hammer/docs/11-bootstrap.md

SDD 11 — Bootstrap from-scratch (track posterior)

Estado: diseño. Abre el track posterior del SDD 10: bajar de "hammer sobre Alpine" a "hammer sobre sí mismo". No bloquea ninguna Fase 0–6 (ya cerradas); reusa el laboratorio de build (SDD 02) sin retrabajo.

1. El problema: el cordón umbilical

Hoy el userland que hammer muta es el de Alpine (musl + busybox ya cocidos). Eso fue deliberado (ADR 0002): validar la capa AI-nativa antes de gastar meses en un bootstrap. Validada esa capa, el track posterior responde una sola pregunta:

¿Puede hammer compilar el sistema completo que ejecuta, sin pedirle nada al host más que un toolchain semilla fijado por hash?

Si la respuesta es sí y el resultado es bit-reproducible, hammer deja de heredar la confianza de Alpine y la deriva de su propio log de transparencia.

2. Principios (heredados, no nuevos)

• Todo es una receta sellada. Cada pieza del bootstrap es un Recipe (SDD 02 §1) cuyo artefacto se direcciona por hash en el Store. El bootstrap es un subgrafo del grafo de dependencias que ya construye el lab, no un mecanismo aparte.
• Nada del host entra al hash. El único insumo externo es el toolchain semilla, y entra como un artefacto importado con su sha256 fijado (ADR 0006), igual que un tarball upstream. El host aporta un kernel para correr procesos y nada más.
• zig cc es la semilla primaria (ADR 0003): un binario hermético = compilador C/C++ + musl + headers, cross al target. Escotilla musl-cross-make (gcc+musl) detrás de la misma interfaz de receta (compiler = "gcc") para los paquetes con gcc-ismos.

3. Las tres etapas

        host (sólo kernel + seed pinned)
                 │
   ┌─────────────▼─────────────┐
   │ Stage 0 — toolchain semilla│  zig (o musl-cross-make) ingerido al store,
   │   sellado por hash         │  fijado por sha256. Cross → x86_64-linux-musl.
   └─────────────┬─────────────┘
                 │ artifact_hash(seed)  ← dependencia de build de todo lo demás
   ┌─────────────▼─────────────┐
   │ Stage 1 — userland mínimo  │  musl, busybox/toybox, init arje, hammerd,
   │   cross-compilado          │  cross-compilados CON Stage 0. Sale un rootfs sellado.
   └─────────────┬─────────────┘
                 │ rootfs_hash(stage1)
   ┌─────────────▼─────────────┐
   │ Stage 2 — rebuild nativo   │  DENTRO del rootfs Stage 1 (bwrap/chroot/VM),
   │   y verificación           │  recompila toolchain+userland con las herramientas
   └────────────────────────────┘  de Stage 1, NO las del host. Compara hashes.

Stage 0 — Toolchain semilla

Modelamos el toolchain semilla como una fuente fijada, no como un build: un Source de tipo tarball con sha256 pinned (zig-<ver>-linux-x86_64.tar.xz, o el tarball de musl-cross-make). hammer-bootstrap lo descarga (fuera del sandbox, como hammer_build::download ya hace para patch_url/content_url), verifica el sha256 antes de sellarlo, y lo deposita en el store con un artifact_hash derivado de ese sha256. A partir de ahí el resto del bootstrap depende del hash del store, no de la ruta del host.

Salida: seed_hash (artefacto del toolchain en el store).

Stage 1 — Userland mínimo

Un conjunto de recetas cuyo [deps].build incluye seed_hash. El conjunto mínimo que arranca y se administra solo:

Pieza	Por qué	Compilador
musl	libc del target	zig cc (estático)
busybox o toybox	coreutils + shell	zig cc (estático)
arje	init: PID 1 + supervisión (ADR 0007)	toolchain Rust
hammerd	diario + bus de agente + watcher, servicio supervisado por arje	toolchain Rust

Todo se enlaza estático o con rpath controlado (sin depender del loader del host). El resultado se ensambla en un rootfs (árbol FHS) que a su vez se sella como un artefacto del store (stage1_hash). El init no se escribe de cero: se adopta arje (ADR 0007), cuyo PID 1 con supervisión real entrega el CRASHED real que la Fase 5 dejó diferido — hammerd corre como servicio bajo arje.

El kernel no es el foco de este hito: se importa pinned (como la semilla) para poder correr el rootfs. Construirlo desde fuente es un sub-ítem posterior, ortogonal al auto-alojamiento del userland.

Stage 2 — Rebuild nativo y verificación

El corte del cordón. Dentro del rootfs Stage 1 (primero vía bwrap/chroot, luego en la VM destino), se reconstruyen Stage 0' y Stage 1' usando sólo las herramientas de Stage 1. Se compara:

hash(stage1)   vs   hash(stage1')

• Iguales ⇒ el sistema se compila a sí mismo bit a bit: reproducible y auto-alojado. Hito cumplido.
• Distintos ⇒ hay no-determinismo (timestamps, paths embebidos, orden de enlace). Se caza y se elimina; es exactamente el trabajo que SDD 09 §2 exige.

4. Manifiesto de bootstrap (embrión del log de transparencia) ✅

Cada etapa anota una línea (stage, recipe_hash, artifact_hash, seed_hash, ts) en un bootstrap.json versionado (en la raíz del store). Ese manifiesto es la semilla del log de transparencia (SDD 09 §4): un tercero reproduce el bootstrap y verifica que sus hashes coinciden con los publicados, sin confiar en el binario del autor.

Implementado en hammer-bootstrap::manifest (BootstrapManifest / StageEntry): append-only e idempotente (de-dup por (stage, artifact_hash)), escritura atómica, y ts que no entra en ningún hash (dos reproducciones del mismo bootstrap difieren a lo sumo en ese campo). Stage 0 ya anota su línea: recipe_hash = None (la semilla se ingiere, no se compila) y artifact_hash == seed_hash (la semilla es a la vez insumo y producto).

5. Interfaz

Nuevo crate hammer-bootstrap (orquestador) sobre hammer-build + hammer-core::Store. No introduce mecanismo nuevo de build: encadena recetas y persiste el manifiesto.

// hammer-bootstrap
pub fn stage0(seed: &SeedSpec, store: &Store) -> Result<ArtifactHash>;       // ✅ toolchain semilla
pub fn stage1(seed: &ArtifactHash, store: &Store) -> Result<RootfsHash>;     // ☐ userland mínimo
pub fn stage2(stage1: &RootfsHash, store: &Store) -> Result<VerifyReport>;   // ☐ rebuild + diff
pub fn all(seed: &SeedSpec, store: &Store) -> Result<BootstrapManifest>;     // ☐

SeedSpec { kind, version, url, sha256 } es la identidad pinned de la semilla; seed_hash() deriva el ArtifactHash de (kind, version, sha256) — no del url ni del host, así que cualquier espejo del mismo tarball produce el mismo artefacto.

CLI (implementado lo de Stage 0; el resto pendiente):

hammer bootstrap stage0 --url URL --sha256 HEX --version V [--seed zig|musl-cross-make]   # ✅
hammer bootstrap stage1 [--target x86_64-linux-musl]                                       # ☐
hammer bootstrap stage2 --verify                                                           # ☐
hammer bootstrap --all                # las tres + reporte de reproducibilidad             # ☐

6. Decisiones abiertas (fijadas en ADR 0008)

• Semilla primaria: zig vs musl-cross-make. Inclinación: zig por hermeticidad (ADR 0003), con musl-cross-make como escotilla por receta.
• busybox vs toybox para el userland mínimo (licencia vs cobertura de comandos).
• Particionado/montaje de /store y /var/lib/hammer en la imagen destino (track posterior del roadmap).
• Kernel: importado pinned ahora; from-source después.

7. Hecho cuando

hammer bootstrap --all produce un rootfs que, ejecutado en la VM destino, reconstruye su propio toolchain y userland con hashes idénticos a los publicados, sin que ninguna herramienta del host entre al resultado. Ese día Alpine deja de ser una dependencia y pasa a ser, a lo sumo, una conveniencia de desarrollo.