1# `crates/core/` — Init Arje (absorbido) + Protocolo Brahman
2
3El directorio agrupa **dos linajes** que se fusionaron al absorberse arje
4dentro del workspace de brahman:
5
6| linaje      | prefijo      | función                                          |
7| ----------- | ------------ | ------------------------------------------------ |
8| `arje`      | `ente-*`     | Init (PID 1), encarnación Linux, compat systemd  |
9| `brahman`   | `brahman-*`  | Tarjeta canónica, handshake, broker, admin       |
10
11No están en sub-carpetas físicas porque el workspace declara los paths uno
12a uno en `Cargo.toml` raíz y muchos `Cargo.toml` hijos usan `path =
13"../ente-X"`. El agrupamiento siguiente es **lógico**: cada crate se
14encuentra como `crates/core/<nombre>`.
15
16---
17
18## 1. Init / PID 1
19
20| crate           | tipo       | resumen                                                            |
21| --------------- | ---------- | ------------------------------------------------------------------ |
22| `ente-zero`     | binario    | PID 1 del fractal. Bucle primordial (reap + bus + handshake).      |
23| `ente-kernel`   | lib        | `bootstrap_kernel_surface()`, subreaper, SIGCHLD/uevent streams.   |
24| `ente-soma`     | lib (shim) | Re-export sobre `crates/shared/ente-incarnate` (clone+ns+cgroup).  |
25| `ente-snapshot` | lib        | `FractalSnapshot` JSON — checkpoint/restore del grafo de Cards.    |
26
27## 2. Contratos canónicos
28
29| crate              | resumen                                                              |
30| ------------------ | -------------------------------------------------------------------- |
31| `brahman-card`     | `Card { soma, payload, flow, permissions, supervision, genesis }`.   |
32| `brahman-card-wit` | Extracción de interfaces WIT de componentes WASM.                    |
33| `brahman-cards`    | Helpers para construir Cards típicas (consumer/producer/broker).     |
34| `ente-card`        | Alias histórico — re-export de `brahman-card` con nombres legacy.    |
35
36## 3. Discovery / Routing
37
38| crate                | resumen                                                            |
39| -------------------- | ------------------------------------------------------------------ |
40| `brahman-handshake`  | Protocolo Init↔módulo (Hello, Ping, ListSessions) postcard/Unix.   |
41| `brahman-broker`     | Service locator: empareja `flow.input` ↔ `flow.output` por tipo.   |
42| `brahman-admin`      | Socket separado para snapshots de sesiones + matches.              |
43
44## 4. IPC interno + Storage
45
46| crate         | resumen                                                                 |
47| ------------- | ----------------------------------------------------------------------- |
48| `ente-bus`    | Unix SOCK_STREAM con framing postcard. `Announce`/`Invoke`/`ListEntes`. |
49| `ente-cas`    | Content-addressed storage SHA-256 (blobs Wasm, audit log).              |
50| `ente-wasm`   | Encarna `Payload::Wasm` vía `wasmi` en thread dedicado.                 |
51
52## 5. Cerebro / Observabilidad
53
54| crate         | resumen                                                                  |
55| ------------- | ------------------------------------------------------------------------ |
56| `ente-brain`  | Rule engine + observer estadístico + audit log con hash chain a CAS.     |
57| `ente-echo`   | Ente de prueba — provee `Capability::Endpoint(echo)` para smoke tests.   |
58
59## 6. Compat systemd (shims D-Bus)
60
61Cada shim es un binario que se anuncia con un nombre well-known
62`org.freedesktop.X1` y traduce las llamadas al bus interno. Esto permite
63que GNOME/KDE/aplicaciones legacy arranquen sobre arje sin systemd:
64
65| binario                     | reemplaza             | nombre D-Bus                        |
66| --------------------------- | --------------------- | ----------------------------------- |
67| `ente-logind-compat`        | `systemd-logind`      | `org.freedesktop.login1`            |
68| `ente-hostnamed-compat`     | `systemd-hostnamed`   | `org.freedesktop.hostname1`         |
69| `ente-timedated-compat`     | `systemd-timedated`   | `org.freedesktop.timedate1`         |
70| `ente-localed-compat`       | `systemd-localed`     | `org.freedesktop.locale1`           |
71| `ente-journald-compat`      | `systemd-journald`    | `org.freedesktop.LogControl1`       |
72| `ente-resolved-compat`      | `systemd-resolved`    | `org.freedesktop.resolve1`          |
73| `ente-polkit-compat`        | `polkitd`             | `org.freedesktop.PolicyKit1`        |
74| `ente-machined-compat`      | `systemd-machined`    | `org.freedesktop.machine1`          |
75| `ente-systemd1-compat`      | `systemd` (Manager)   | `org.freedesktop.systemd1`          |
76| `ente-notify-compat`        | `sd_notify` socket    | `/run/systemd/notify` (datagram)    |
77| `ente-timer-compat`         | `systemd-timer`       | (cron-like, sin D-Bus)              |
78| `ente-tmpfiles-compat`      | `systemd-tmpfiles`    | (aplica tmpfiles.d al boot)         |
79| `ente-binfmt-compat`        | `systemd-binfmt`      | (registra binfmt_misc handlers)     |
80| `ente-policy-provider`      | (interno)             | proveedor de decisiones polkit      |
81
82---
83
84## Crates relacionados fuera de `core/`
85
86Dependen del Init pero viven en `crates/shared/`:
87
88- `ente-incarnate` — rutina pura de `clone(2) + namespaces + cgroup +
89  rlimits + cpu_affinity`. Reusable por shipote y supervisores no-PID-1.
90- `brahman-net` — malla P2P opcional (libp2p) que extiende el handshake.
91- `brahman-sidecar` — helper `spawn(card)` para que las apps se presenten
92  al Init sin reimplementar el cliente del handshake.
93
94## Convención de uso
95
96Para arrancar el Init y ejecutar Cards, ver:
97
98- **Seeds estándar** en `seeds/`.
99- **Build de initramfs** con `scripts/build-arje-initrd.sh`.
100- **Boot en QEMU / bare metal** documentado en `docs/arje-boot.md`.