refactor(naming): A1 — ente→arje, vista→revista, pluma→fana

Rename batch de la Fase A del PLAN_MACRO:
- 25 crates ente-* → arje-* (protocol/init/runtime/compat). El linaje
  arje (init Linux) queda con prefijo coherente.
- vista → revista (revista-core + revista-web).
- pluma → fana (fana-md + fana-md-reader-web). fana absorbe el linaje
  markdown de pluma; será el writer DAG editor (prioridad alta).

Cambios:
- git mv de 29 crate dirs + 2 SDDs
- package/lib/bin names + path refs + imports .rs reescritos
- workspace Cargo.toml + comentarios de sección
- SDDs de init/runtime/compat/protocol actualizados a arje-
- SDD de revista + SDD de fana (reescrito: writer DAG editor)
- docs/STATUS.md, ROADMAP.md, PLAN_MACRO.md, arje-boot.md,
  arje-replace-systemd.md actualizados
- docs/changelog/akasha.md → chasqui.md

scripts/rename-fase-a.py idempotente (--dry-run soportado).
cargo check --workspace verde.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
sergio
2026-05-20 00:10:14 +00:00
parent 3fc6dcfa72
commit b83d40a833
159 changed files with 2384 additions and 1111 deletions
+30 -30
View File
@@ -1,9 +1,9 @@
# Booteando arje — initramfs, QEMU y bare metal
`arje` es el init absorbido por brahman: `ente-zero` corre como PID 1, lee
`arje` es el init absorbido por brahman: `arje-zero` corre como PID 1, lee
la **Tarjeta Semilla** (`/ente/seed.card.json`), monta `/proc /sys /dev
/sys/fs/cgroup`, y encarna recursivamente cada Card declarada en
`genesis` vía `ente-incarnate::Incarnator` (`clone(2)` + namespaces + cgroup v2).
`genesis` vía `arje-incarnate::Incarnator` (`clone(2)` + namespaces + cgroup v2).
Este documento describe el ciclo completo:
@@ -21,11 +21,11 @@ Este documento describe el ciclo completo:
El initrd es un **CPIO + gzip** (formato `newc`, estándar Linux). Su raíz:
```
/init wrapper sh, ejecuta /sbin/ente-zero
/sbin/ente-zero PID 1 (musl-static por default)
/usr/sbin/ente-echo
/usr/sbin/ente-policy-provider
/usr/sbin/ente-*-compat 13 shims D-Bus (logind, hostnamed, …)
/init wrapper sh, ejecuta /sbin/arje-zero
/sbin/arje-zero PID 1 (musl-static por default)
/usr/sbin/arje-echo
/usr/sbin/arje-policy-provider
/usr/sbin/arje-*-compat 13 shims D-Bus (logind, hostnamed, …)
/usr/bin/brahman-status CLI: snapshot del broker (sesiones + matches)
/usr/bin/busctl CLI: bus interno (list-entes, announce, …)
/usr/bin/brainctl CLI: cerebro (rules, entropy, crystals)
@@ -36,14 +36,14 @@ El initrd es un **CPIO + gzip** (formato `newc`, estándar Linux). Su raíz:
```
Path canónico de la semilla en **prod**: `/ente/seed.card.json` (ver
`crates/core/ente-zero/src/seed.rs`). En **dev** (no PID 1):
`crates/core/arje-zero/src/seed.rs`). En **dev** (no PID 1):
`./seed.card.json` en el cwd, o se sintetiza una mínima.
## 2. Build del initrd
### 2a. Por qué musl-static
`ente-zero` corre como **PID 1**: si tiene cualquier dependencia dinámica
`arje-zero` corre como **PID 1**: si tiene cualquier dependencia dinámica
(`libgcc_s.so.1`, `libc.so.6`, `ld-linux-x86-64.so.2`) que no está
presente en el initramfs, el kernel paniquea con
`error while loading shared libraries: libgcc_s.so.1`.
@@ -96,7 +96,7 @@ ARJE_TARGET=x86_64-unknown-linux-gnu scripts/build-arje-initrd.sh
1. Verifica que el target musl esté instalado; si no, da el comando
exacto para instalarlo.
2. `cargo build --release --target x86_64-unknown-linux-musl` para
`ente-zero` + los 14 shims compat.
`arje-zero` + los 14 shims compat.
3. Sanity-check con `file`: aborta si algún binario quedó dinámico.
4. Valida la seed con `seeds/validate.sh` (parse + `Card::validate`).
5. Verifica que `busybox` sea estático (también aborta si es dinámico).
@@ -164,9 +164,9 @@ wget -O /tmp/vmlinuz \
| `loglevel=7` | log del kernel hasta debug |
| `quiet` | silencia banner kernel |
| `RUST_LOG=trace` | (no se interpreta; usar env en `/init`) |
| `init=/sbin/ente-zero` | salta `/init`, ejecuta directo (no recomendado) |
| `init=/sbin/arje-zero` | salta `/init`, ejecuta directo (no recomendado) |
`ente-zero` lee `RUST_LOG` y `BRAHMAN_*` del env. Para setearlas, editar
`arje-zero` lee `RUST_LOG` y `BRAHMAN_*` del env. Para setearlas, editar
`/init` antes de empaquetar, o agregar `-fw_cfg name=opt/foo,...` a qemu.
### 3d. Smoke test esperado
@@ -174,9 +174,9 @@ wget -O /tmp/vmlinuz \
Con `seeds/arje-prod.card.json`:
```
ente-zero despierta como PID 1
arje-zero despierta como PID 1
Tarjeta Semilla cargada y validada path=/ente/seed.card.json
bus interno escuchando path=/run/ente-bus.sock
bus interno escuchando path=/run/arje-bus.sock
brahman handshake escuchando (Unix) socket=/run/brahman-init.sock
brahman admin escuchando socket=/run/brahman-admin.sock
instanciando genesis seed=arje.seed.prod count=16
@@ -242,8 +242,8 @@ de implementar como `Capability::SwitchRoot`.
seeds/validate.sh seeds/arje-prod.card.json
```
El script carga la Card vía `ente_brain::load_card_file()` (que llama a
`brahman_card::Card::validate()`) y verifica que `ente-zero` la encarne
El script carga la Card vía `arje_brain::load_card_file()` (que llama a
`brahman_card::Card::validate()`) y verifica que `arje-zero` la encarne
hasta `instanciando genesis`.
### 5c. Customizar
@@ -294,7 +294,7 @@ Validación clave (`brahman_card::Card::validate`):
### 6a. Tracing
`ente-zero` usa `tracing-subscriber`. Default: `ente_zero=debug,info`.
`arje-zero` usa `tracing-subscriber`. Default: `arje_zero=debug,info`.
Override con `RUST_LOG`:
```bash
@@ -309,10 +309,10 @@ los sockets caen al fallback `/tmp/`:
| socket | env override | servicio |
| ---------------------------- | ----------------------- | ----------------------------------------- |
| `/tmp/ente-bus-*.sock` | `ENTE_BUS_SOCK` | bus interno (Announce/Invoke/ListEntes) |
| `/tmp/arje-bus-*.sock` | `ENTE_BUS_SOCK` | bus interno (Announce/Invoke/ListEntes) |
| `/tmp/brahman-init.sock` | `BRAHMAN_INIT_SOCKET` | handshake brahman |
| `/tmp/brahman-admin.sock` | `BRAHMAN_ADMIN_SOCKET` | snapshots de sesiones + matches |
| `/tmp/ente-brain.sock` | `ENTE_BRAIN_SOCK` | introspección del cerebro (rules, observer) |
| `/tmp/arje-brain.sock` | `ENTE_BRAIN_SOCK` | introspección del cerebro (rules, observer) |
El initrd trae 3 CLI clients precompilados en `/usr/bin/`:
@@ -351,7 +351,7 @@ arje# busctl list-entes
arje# brainctl top 5
spawn 14
ente_died 0
arje_died 0
```
@@ -365,8 +365,8 @@ arje# socat - UNIX-CONNECT:/tmp/brahman-admin.sock | jq .
### 6c. Snapshot / restore
```
ente-zero --checkpoint /ente/checkpoint.json # escribe al cerrar
ente-zero --restore /ente/checkpoint.json # reconstruye al boot
arje-zero --checkpoint /ente/checkpoint.json # escribe al cerrar
arje-zero --restore /ente/checkpoint.json # reconstruye al boot
```
Snapshot adjunto del cerebro: `/ente/checkpoint.brain.json`.
@@ -374,7 +374,7 @@ Snapshot adjunto del cerebro: `/ente/checkpoint.brain.json`.
### 6d. Metrics
```
ente-zero --metrics-addr 127.0.0.1:9911
arje-zero --metrics-addr 127.0.0.1:9911
```
Endpoint Prometheus desde dentro de la VM. Para exponerlo al host bajo
@@ -382,20 +382,20 @@ QEMU, agregar `-netdev user,hostfwd=tcp::9911-:9911 -device virtio-net,netdev=
### 6e. Modo DEV en host (sin PID 1)
`ente-zero` detecta si su PID != 1 y entra en **DEV MODE**: no monta
`arje-zero` detecta si su PID != 1 y entra en **DEV MODE**: no monta
kernel surface, no se vuelve subreaper, sale tras 4 s. Útil para
iterar Cards en el host:
```bash
mkdir /tmp/arje-test && cp seeds/arje-minimal.card.json /tmp/arje-test/seed.card.json
cd /tmp/arje-test && target/release/ente-zero
cd /tmp/arje-test && target/release/arje-zero
```
## 7. Troubleshooting
### 7a. `error while loading shared libraries: libgcc_s.so.1` al boot
**Causa**: el `/sbin/ente-zero` del initrd se compiló contra glibc
**Causa**: el `/sbin/arje-zero` del initrd se compiló contra glibc
(`x86_64-unknown-linux-gnu`) y depende dinámicamente de `libgcc_s.so.1`,
`libc.so.6`, `ld-linux-x86-64.so.2`. Esas libs no están en el initramfs,
el kernel mata PID 1 → panic.
@@ -411,7 +411,7 @@ scripts/build-arje-initrd.sh # ya usa musl por default
Verificar manualmente que el binario quedó estático:
```bash
file target/x86_64-unknown-linux-musl/release/ente-zero
file target/x86_64-unknown-linux-musl/release/arje-zero
# → "ELF 64-bit LSB executable, ..., statically linked, ..."
```
@@ -422,7 +422,7 @@ recomendado.
### 7b. Kernel panic: `Kernel panic - not syncing: Attempted to kill init!`
**Causa**: `ente-zero` salió con error antes de bind del bus, o `/init`
**Causa**: `arje-zero` salió con error antes de bind del bus, o `/init`
crashed antes de exec. PID 1 muriendo = panic kernel.
**Fix**: agregar `panic=10` al cmdline (ya está en el script) para
@@ -464,9 +464,9 @@ target-feature=+crt-static"` o aislando el feature problemático.
- [ ] `rustup target add x86_64-unknown-linux-musl` instalado en el host build.
- [ ] `musl-tools` (Debian/Ubuntu) o equivalente disponible.
- [ ] `busybox-static` disponible para vendorear userspace.
- [ ] `cargo build --release --target x86_64-unknown-linux-musl -p ente-zero`
- [ ] `cargo build --release --target x86_64-unknown-linux-musl -p arje-zero`
compila sin warnings.
- [ ] `file target/x86_64-unknown-linux-musl/release/ente-zero` reporta
- [ ] `file target/x86_64-unknown-linux-musl/release/arje-zero` reporta
"statically linked".
- [ ] `seeds/validate.sh seeds/arje-prod.card.json` → OK.
- [ ] `scripts/build-arje-initrd.sh` produce `out/arje.initrd.cpio.gz`.