# `crates/core/` — Init Arje (absorbido) + Protocolo Brahman

El directorio agrupa **dos linajes** que se fusionaron al absorberse arje
dentro del workspace de brahman:

| linaje      | prefijo      | función                                          |
| ----------- | ------------ | ------------------------------------------------ |
| `arje`      | `ente-*`     | Init (PID 1), encarnación Linux, compat systemd  |
| `brahman`   | `brahman-*`  | Tarjeta canónica, handshake, broker, admin       |

No están en sub-carpetas físicas porque el workspace declara los paths uno
a uno en `Cargo.toml` raíz y muchos `Cargo.toml` hijos usan `path =
"../ente-X"`. El agrupamiento siguiente es **lógico**: cada crate se
encuentra como `crates/core/<nombre>`.

---

## 1. Init / PID 1

| crate           | tipo       | resumen                                                            |
| --------------- | ---------- | ------------------------------------------------------------------ |
| `ente-zero`     | binario    | PID 1 del fractal. Bucle primordial (reap + bus + handshake).      |
| `ente-kernel`   | lib        | `bootstrap_kernel_surface()`, subreaper, SIGCHLD/uevent streams.   |
| `ente-soma`     | lib (shim) | Re-export sobre `crates/shared/ente-incarnate` (clone+ns+cgroup).  |
| `ente-snapshot` | lib        | `FractalSnapshot` JSON — checkpoint/restore del grafo de Cards.    |

## 2. Contratos canónicos

| crate              | resumen                                                              |
| ------------------ | -------------------------------------------------------------------- |
| `brahman-card`     | `Card { soma, payload, flow, permissions, supervision, genesis }`.   |
| `brahman-card-wit` | Extracción de interfaces WIT de componentes WASM.                    |
| `brahman-cards`    | Helpers para construir Cards típicas (consumer/producer/broker).     |
| `ente-card`        | Alias histórico — re-export de `brahman-card` con nombres legacy.    |

## 3. Discovery / Routing

| crate                | resumen                                                            |
| -------------------- | ------------------------------------------------------------------ |
| `brahman-handshake`  | Protocolo Init↔módulo (Hello, Ping, ListSessions) postcard/Unix.   |
| `brahman-broker`     | Service locator: empareja `flow.input` ↔ `flow.output` por tipo.   |
| `brahman-admin`      | Socket separado para snapshots de sesiones + matches.              |

## 4. IPC interno + Storage

| crate         | resumen                                                                 |
| ------------- | ----------------------------------------------------------------------- |
| `ente-bus`    | Unix SOCK_STREAM con framing postcard. `Announce`/`Invoke`/`ListEntes`. |
| `ente-cas`    | Content-addressed storage SHA-256 (blobs Wasm, audit log).              |
| `ente-wasm`   | Encarna `Payload::Wasm` vía `wasmi` en thread dedicado.                 |

## 5. Cerebro / Observabilidad

| crate         | resumen                                                                  |
| ------------- | ------------------------------------------------------------------------ |
| `ente-brain`  | Rule engine + observer estadístico + audit log con hash chain a CAS.     |
| `ente-echo`   | Ente de prueba — provee `Capability::Endpoint(echo)` para smoke tests.   |

## 6. Compat systemd (shims D-Bus)

Cada shim es un binario que se anuncia con un nombre well-known
`org.freedesktop.X1` y traduce las llamadas al bus interno. Esto permite
que GNOME/KDE/aplicaciones legacy arranquen sobre arje sin systemd:

| binario                     | reemplaza             | nombre D-Bus                        |
| --------------------------- | --------------------- | ----------------------------------- |
| `ente-logind-compat`        | `systemd-logind`      | `org.freedesktop.login1`            |
| `ente-hostnamed-compat`     | `systemd-hostnamed`   | `org.freedesktop.hostname1`         |
| `ente-timedated-compat`     | `systemd-timedated`   | `org.freedesktop.timedate1`         |
| `ente-localed-compat`       | `systemd-localed`     | `org.freedesktop.locale1`           |
| `ente-journald-compat`      | `systemd-journald`    | `org.freedesktop.LogControl1`       |
| `ente-resolved-compat`      | `systemd-resolved`    | `org.freedesktop.resolve1`          |
| `ente-polkit-compat`        | `polkitd`             | `org.freedesktop.PolicyKit1`        |
| `ente-machined-compat`      | `systemd-machined`    | `org.freedesktop.machine1`          |
| `ente-systemd1-compat`      | `systemd` (Manager)   | `org.freedesktop.systemd1`          |
| `ente-notify-compat`        | `sd_notify` socket    | `/run/systemd/notify` (datagram)    |
| `ente-timer-compat`         | `systemd-timer`       | (cron-like, sin D-Bus)              |
| `ente-tmpfiles-compat`      | `systemd-tmpfiles`    | (aplica tmpfiles.d al boot)         |
| `ente-binfmt-compat`        | `systemd-binfmt`      | (registra binfmt_misc handlers)     |
| `ente-policy-provider`      | (interno)             | proveedor de decisiones polkit      |

---

## Crates relacionados fuera de `core/`

Dependen del Init pero viven en `crates/shared/`:

- `ente-incarnate` — rutina pura de `clone(2) + namespaces + cgroup +
  rlimits + cpu_affinity`. Reusable por shipote y supervisores no-PID-1.
- `brahman-net` — malla P2P opcional (libp2p) que extiende el handshake.
- `brahman-sidecar` — helper `spawn(card)` para que las apps se presenten
  al Init sin reimplementar el cliente del handshake.

## Convención de uso

Para arrancar el Init y ejecutar Cards, ver:

- **Seeds estándar** en `seeds/`.
- **Build de initramfs** con `scripts/build-arje-initrd.sh`.
- **Boot en QEMU / bare metal** documentado en `docs/arje-boot.md`.