1# Runbook — validar Stage 1 booteando en QEMU
2
3> Operativo, no diseño. Valida end-to-end que el rootfs que produce
4> `hammer bootstrap stage1` ([SDD 11](../11-bootstrap.md)) **bootea con arje-zero como PID 1**
5> ([SDD 12](../12-init-real.md)), levanta `hammerd` + getty bajo supervisión, y que el **`CRASHED`
6> real** funciona.
7>
8> **Esto es un procedimiento, no un transcript verificado.** La lógica de ensamblado/hash/seed está
9> cubierta por unit tests (y la seed se validó contra `card_core::Card`), pero el cross-compile y el
10> boot reales **no** se han corrido todavía — ese es justo el punto de este runbook. La primera
11> corrida puede destapar ajustes (link, `/dev/console`, getty/tty); §7 los anticipa.
12
13## 0. Lo que valida / lo que no
14
15- **Valida:** que el árbol sellado por `stage1` arranca como sistema: arje-zero monta los pseudo-FS,
16  carga la seed, incarna `hammerd` y la getty, y al matar `hammerd` lo reinicia con backoff (el
17  `CRASHED` que la Fase 5 difirió).
18- **No valida (aún):** bus único (B.2), overlay del store (I4), atestación (A1/A2), kernel
19  from-source. Aquí el kernel es prestado del host; el overlay no se monta.
20
21## 1. Prerrequisitos
22
23- **Lab de dev** montado: `./scripts/bootstrap-devfs.sh` (deja `.dev-fs/alpine` + `.dev-fs/tools/zig`).
24- **Red**: el build de `hammerd` y `arje-zero` clona repos git (hammer, tawasuyu) y corre
25  `cargo vendor` en el fetch. El build hermético del sandbox es `--offline`, pero el fetch necesita red.
26- **Herramientas host**: `qemu-system-x86_64`, un kernel x86_64 (`/boot/vmlinuz-*`), `cpio`, `gzip`.
27- **Espacio/tiempo**: construir `arje-zero` vendorea las deps del **monorepo tawasuyu entero** — es
28  pesado y lento la primera vez (se cachea después).
29- **El binario `hammer`**: `cargo build --release -p hammer-cli` ⇒ `./target/release/hammer`.
30
31> El store debe vivir en la raíz del repo (`./store`) para que `BuildConfig` resuelva
32> `.dev-fs/alpine` como hermano (`store/..` = repo root). El toolchain de Stage 1 **no** es el de
33> `.dev-fs`: es la semilla de Stage 0 (paso 2), que `stage1` enchufa como `zig_dir` del sandbox.
34
35## 2. Stage 0 — ingerir la semilla (zig)
36
37```sh
38export HAMMER=./target/release/hammer
39export STORE=./store
40
41"$HAMMER" --store "$STORE" bootstrap stage0 \
42  --url https://ziglang.org/download/0.16.0/zig-x86_64-linux-0.16.0.tar.xz \
43  --sha256 70e49664a74374b48b51e6f3fdfbf437f6395d42509050588bd49abe52ba3d00 \
44  --version 0.16.0
45# → imprime el seed_hash (b3:...). Guardalo:
46SEED="b3:..."   # pegá el hash impreso
47```
48
49Idempotente: re-correr no re-descarga. La semilla queda sellada como `seed-zig` en el store y anota
50su línea en `bootstrap.json`.
51
52## 3. Stage 1 — construir y sellar el rootfs
53
54```sh
55"$HAMMER" --store "$STORE" bootstrap stage1 --seed-hash "$SEED" --recipes recipes
56# construye musl + busybox + hammerd + arje-zero, ensambla el rootfs FHS y lo sella.
57# → imprime el rootfs_hash (b3:...).
58
59# El árbol sellado (read-only) del rootfs:
60ROOTFS_DIR=$(ls -d "$STORE"/*-stage1-rootfs)
61echo "$ROOTFS_DIR"
62ls "$ROOTFS_DIR"/ente/seed.card.json "$ROOTFS_DIR"/sbin/init "$ROOTFS_DIR"/usr/bin/{hammerd,arje-zero}
63```
64
65Necesita red (git clone + `cargo vendor`). Si un build Cargo falla en el link (`-lgcc_s`) o por
66static-PIE, ver §7 — el `zig cc` del lab debería resolver `-lgcc_s` (bitácora M2 del plan arje↔hammer).
67
68## 4. Empaquetar el rootfs como initramfs
69
70El árbol del store ya trae `/sbin/init`→`/usr/bin/arje-zero` y `/ente/seed.card.json`. Se empaqueta
71como cpio `newc` + gzip (formato initramfs):
72
73```sh
74( cd "$ROOTFS_DIR" && find . -print0 | cpio --null -o --format=newc ) | gzip -9 > /tmp/stage1.cpio.gz
75ls -lh /tmp/stage1.cpio.gz
76```
77
78`cpio newc` preserva symlinks y hardlinks. El symlink `/sbin/init`→`/usr/bin/arje-zero` es absoluto:
79en un initramfs resuelve dentro de su propia raíz. (Si el kernel no auto-monta `devtmpfs`, ver §7 por
80el nodo `/dev/console`.)
81
82## 5. Bootear en QEMU
83
84```sh
85qemu-system-x86_64 -m 512 -nographic \
86  -kernel /boot/vmlinuz-linux \
87  -initrd /tmp/stage1.cpio.gz \
88  -append "console=ttyS0 rdinit=/sbin/init"
89```
90
91- `rdinit=/sbin/init` — el default de un initramfs es `/init`; lo sobreescribimos a `/sbin/init`
92  (→arje-zero). Alternativa directa: `rdinit=/usr/bin/arje-zero`.
93- `console=ttyS0` + `-nographic` — consola serie, donde arje escribe y la getty se engancha.
94- Salir de QEMU: `Ctrl-A` luego `X`.
95
96## 6. Criterios de éxito (qué observar)
97
981. **PID 1**: en kmsg/consola, arje-zero loguea *"despierta como PID 1"*.
992. **Pseudo-FS**: monta `/proc /sys /dev` sin error fatal (best-effort; un `EBUSY` se ignora).
1003. **Seed**: carga `/ente/seed.card.json` sin *"card inválida"* (ya validada contra `card_core::Card`).
1014. **hammerd**: arranca como Ente — su tracing aparece y/o crea `/run/agent.sock`.
1025. **getty**: aparece un prompt de shell (`/bin/sh`) en `ttyS0`.
1036. **CRASHED real** — la prueba clave. En el shell:
104   ```sh
105   kill "$(pidof hammerd)"
106   ```
107   arje registra el `on_death(ExitStatus)` y **reinicia hammerd tras el backoff** (200 ms → ×2…).
108   Eso es el `CRASHED` que la Fase 5 dejó diferido, ahora manejado por el init propio.
109
110## 7. Troubleshooting (síntoma → causa → fix)
111
112| Síntoma | Causa probable | Fix |
113|---|---|---|
114| `Kernel panic … no init found` | `/sbin/init` no ejecuta | probar `rdinit=/usr/bin/arje-zero`; verificar que el symlink quedó en el cpio (`cpio -tv`) |
115| arje cae a rescue shell *"card inválida"* | la seed no validó | confirmar que `/ente/seed.card.json` se empaquetó; comparar con el schema de `seeds/arje-qemu.card.json` |
116| hammerd/arje-zero: `exec format error` | binario no estático / falta loader | confirmar `link = "static"`; un static-PIE pide `/lib/ld-musl-x86_64.so.1` — para init-clásico desactivar PIE (`-C relocation-model=static`, bitácora M2) |
117| Build Cargo falla en `-lgcc_s` | hueco del toolchain musl dinámico | el lab usa `zig cc` (empaqueta su `compiler-rt`) → no debería aparecer; verificar `compiler = "zig-cc"` en la receta |
118| getty sin prompt | device `console` no engancha tty | probar `argv` con `ttyS0` en vez de `console`; revisar que `/dev/console` existe |
119| `No working init` / sin `/dev/console` | kernel sin auto-mount de devtmpfs | crear el nodo en el cpio (`mknod -m 600 dev/console c 5 1` antes de empaquetar) o usar un kernel con `CONFIG_DEVTMPFS_MOUNT=y` |
120| `cargo vendor` / git clone falla | el fetch necesita red | correr Stage 1 con red; el sandbox de build sigue siendo `--offline` |
121
122## 8. Cross-check opcional — `arje-packager`
123
124arje trae su propio empaquetador (`03_ukupacha/arje/init/arje-packager`):
125`arje-packager --seed <CARD.json> --out <initramfs.cpio.gz> [--bin LABEL=PATH]…`. Útil para comparar
126el initramfs **canónico de arje** contra el que sale del rootfs de hammer (§4). No reemplaza esta
127validación: aquí probamos el rootfs que **hammer** sella, no el que arje arma.