docs(shipote): README + 4 docs en docs/ (ARCHITECTURE, CLI, RECIPES, DEVELOPMENT)

- README.md en crates/modules/shipote/ como entry point. - docs/ARCHITECTURE.md — 11 crates, capas, decisiones (O_CLOEXEC, dirty AtomicBool, pipeline restart entero, etc.) + snapshot versioning. - docs/CLI.md — referencia comando por comando, flags, env vars. - docs/RECIPES.md — specs TOML para workspaces y pipelines típicos. - docs/DEVELOPMENT.md — compilar, correr daemon/shell/CLI, tests, smoke E2E manual, debugging FDs. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-11 17:10:44 +00:00
parent a9124449f9
commit d962fe4601
5 changed files with 888 additions and 0 deletions
@@ -0,0 +1,73 @@
+# shipote
+
+**Runtime de espacios aislados con flujo tipado** dentro del fractal brahman.
+
+shipote no es un shell POSIX. Es un daemon long-running que:
+
+- Aísla procesos en **Workspaces** (cada uno con su `SomaSpec`: namespaces, cgroup, rlimits).
+- Encadena comandos en **Pipelines** (DAG con fan-out, fan-in, taps, replay buffer).
+- **Discierne contenido** sobre cada flow (detecta `application/json`, `text/markdown`, magic bytes, hasta `brahman:card`).
+- Expone **data plane** real: subscribers externos se conectan a Unix sockets y reciben los bytes del stream.
+- Se integra al ecosistema vía `brahman-sidecar` (anuncia Cards al broker).
+
+```
+                         ┌─────────────┐
+                         │  shipote    │  daemon long-running
+                         │  -daemon    │  $XDG_RUNTIME_DIR/shipote.sock
+                         └──────┬──────┘
+                                │ admin protocol (postcard)
+              ┌─────────────────┼─────────────────┐
+              │                 │                 │
+        ┌─────▼─────┐     ┌─────▼─────┐     ┌─────▼─────┐
+        │ shipote   │     │ shipote-  │     │  HTTP /   │
+        │  (CLI)    │     │  shell    │     │  custom   │
+        │           │     │  (GUI)    │     │  (futuro) │
+        └───────────┘     └───────────┘     └───────────┘
+```
+
+## Quick start
+
+```sh
+# 1. Compilar
+cargo build -p shipote-daemon -p shipote-cli
+
+# 2. Arrancar daemon (en una terminal):
+SHIPOTE_LOG=info ./target/debug/shipote-daemon
+
+# 3. En otra terminal:
+./target/debug/shipote health
+./target/debug/shipote workspace create demo.toml
+./target/debug/shipote run -w <ws-id> /bin/echo -- hola
+```
+
+## Estado actual
+
+- **11 crates** en el monorepo. Ver [ARCHITECTURE.md](docs/ARCHITECTURE.md).
+- **85 tests** pasando.
+- Compatible con cualquier supervisor (`ente-incarnate` es reusable — no requiere ser PID 1).
+
+## Documentación
+
+- [**ARCHITECTURE.md**](docs/ARCHITECTURE.md) — qué crates lo componen, cómo se conectan, decisiones clave.
+- [**CLI.md**](docs/CLI.md) — referencia de comandos del binario `shipote`.
+- [**RECIPES.md**](docs/RECIPES.md) — specs TOML de workspaces y pipelines con casos prácticos.
+- [**DEVELOPMENT.md**](docs/DEVELOPMENT.md) — cómo correr daemon, GUI, tests, snapshot.
+
+## Acoplamiento con el resto del monorepo
+
+| Reusa | Propósito |
+|---|---|
+| `ente-incarnate` (extraído de `ente-soma` en Fase 0) | clone(2) + namespaces + cgroup + rlimits |
+| `brahman-card` | tipos `Card`, `SomaSpec`, `Flow`, `TypeRef` |
+| `brahman-sidecar` + `brahman-handshake` | anuncio al broker |
+| `ente-snapshot` filosofía | persistencia (shipote tiene su propio `ShipoteSnapshot` v4) |
+| `yahweh-launcher` + widgets | GUI `shipote-shell` |
+| `shipote-discern` ← usado por | `yahweh-provider-fs` (mime per archivo) y `nouser-core::cluster::pick_lens` |
+
+## Limitaciones declaradas
+
+- **`mount/pid/net/uts/ipc/cgroup` namespaces** requieren `CAP_SYS_ADMIN` o combo con `CLONE_NEWUSER`.
+- **`user` namespace** puede estar bloqueado por sysctl o LSM (apparmor/selinux).
+- **`cgroup` v2 limits** (memory.max, pids.max) requieren delegation. Sin delegation, accounting funciona pero el kernel no enforce.
+- **Pipeline restart** preserva spec pero **no ULIDs** del pipeline_id (cada relaunch genera uno nuevo).
+- **Replay buffer broadcast**: subscribers tarde reciben el snapshot del replay (cap configurable por bytes o chunks), pero pueden perder chunks intermedios si el ring rota antes de conectarse.