tawasuyu/brahman

Rust 483TOML 191Markdown 50JSON 176777 Sutichaykuna

Ch'ipachiy HTTPSninta, git kaqllawan

⎇ 762bf95dfd770cc8bf51f21605bc2cc6cc88ea76 crates/init/SDD.md Markdown · 50 siq'ikuna · 2.3 KB Ñawpa willay ch'uya

feat(arje-incarnate): A5 — pivot_root + OverlayFS f8a2547b4 · sergio · 5 killa ñawpaq

1# init/ — Init (PID 1) y encarnación Linux
2
3**Propósito.** `arje-zero` arranca como PID 1 del fractal. Provee el
4bucle primordial (reap + bus + handshake), bootstrap del kernel
5surface, encarnación de Cards en procesos aislados con namespaces +
6cgroups, y snapshot/restore del grafo.
7
8## Crates
9
10| crate            | tipo    | rol                                                   |
11| ---------------- | ------- | ----------------------------------------------------- |
12| `arje-zero`      | binario | PID 1: reap + handshake server + bus dispatcher       |
13| `arje-kernel`    | lib     | `bootstrap_kernel_surface`, subreaper, SIGCHLD/uevent |
14| `arje-soma`      | lib     | Wrapper 44 LOC sobre `arje-incarnate` (compat API)    |
15| `arje-incarnate` | lib     | `clone(2) + namespaces + cgroup + rlimits + cpu`     |
16|                  |         | + `pivot_root` + OverlayFS (capa base RO + sesión RW)|
17| `arje-snapshot`  | lib     | `FractalSnapshot` JSON: checkpoint del grafo Cards    |
18
19## Dependencias
20
21- `arje-kernel` ← `nix`, `libc`, syscalls Linux puras.
22- `arje-incarnate` reusable: shuma (sandboxes) y supervisores no-PID-1.
23- Consume `protocol/` (handshake server, brahman-net opcional).
24
25## Boot path
26
271. Kernel pasa control → `arje-zero` arranca como `/sbin/init`.
282. Levanta sockets: `/run/brahman/bus`, `/run/brahman/handshake`.
293. Lee `Card` semilla (`seeds/arje-{minimal,host,prod}.card.json`).
304. Para cada `genesis` child Card: `incarnate(card)` → spawn aislado.
315. Reap loop atiende SIGCHLD; bus loop atiende anuncios/invokes.
32
33## Encarnación de rootfs aislado
34
35`arje-incarnate` expone vía `ChildSetup` (hook pre-execve declarativo):
36- `with_overlay(lower, upper, work, merged)` → monta OverlayFS:
37  capa base RO + capa de sesión RW + workdir.
38- `with_pivot_root(new_root, put_old_name)` → `pivot_root` + chdir +
39  desmontaje lazy (`MNT_DETACH`) del root viejo.
40
41Ambas corren en el hijo, post-clone, dentro del mount namespace,
42async-signal-safe. Las consumen `mirada` (compositor) y `matilda` Ghost.
43
44## Estado
45
46Funciona bare metal + QEMU + initramfs (ver `docs/arje-boot.md`). LOC
47~2.2K en init core. `arje-incarnate`: 19 tests verdes (incluye builders
48de overlay/pivot_root). Pendiente: integration testing de pivot_root +
49OverlayFS en entorno con namespaces reales; cobertura de snapshot
50restore con stale fds.

SDD.md

init/ — Init (PID 1) y encarnación Linux

Propósito. arje-zero arranca como PID 1 del fractal. Provee el bucle primordial (reap + bus + handshake), bootstrap del kernel surface, encarnación de Cards en procesos aislados con namespaces + cgroups, y snapshot/restore del grafo.

Crates

crate	tipo	rol
`arje-zero`	binario	PID 1: reap + handshake server + bus dispatcher
`arje-kernel`	lib	`bootstrap_kernel_surface`, subreaper, SIGCHLD/uevent
`arje-soma`	lib	Wrapper 44 LOC sobre `arje-incarnate` (compat API)
`arje-incarnate`	lib	`clone(2) + namespaces + cgroup + rlimits + cpu`
		+ `pivot_root` + OverlayFS (capa base RO + sesión RW)
`arje-snapshot`	lib	`FractalSnapshot` JSON: checkpoint del grafo Cards

Dependencias

arje-kernel ← nix, libc, syscalls Linux puras.
arje-incarnate reusable: shuma (sandboxes) y supervisores no-PID-1.
Consume protocol/ (handshake server, brahman-net opcional).

Boot path

Kernel pasa control → arje-zero arranca como /sbin/init.
Levanta sockets: /run/brahman/bus, /run/brahman/handshake.
Lee Card semilla (seeds/arje-{minimal,host,prod}.card.json).
Para cada genesis child Card: incarnate(card) → spawn aislado.
Reap loop atiende SIGCHLD; bus loop atiende anuncios/invokes.

Encarnación de rootfs aislado

arje-incarnate expone vía ChildSetup (hook pre-execve declarativo):

with_overlay(lower, upper, work, merged) → monta OverlayFS: capa base RO + capa de sesión RW + workdir.
with_pivot_root(new_root, put_old_name) → pivot_root + chdir + desmontaje lazy (MNT_DETACH) del root viejo.

Ambas corren en el hijo, post-clone, dentro del mount namespace, async-signal-safe. Las consumen mirada (compositor) y matilda Ghost.

Estado

Funciona bare metal + QEMU + initramfs (ver docs/arje-boot.md). LOC ~2.2K en init core. arje-incarnate: 19 tests verdes (incluye builders de overlay/pivot_root). Pendiente: integration testing de pivot_root + OverlayFS en entorno con namespaces reales; cobertura de snapshot restore con stale fds.