brahman/crates/modules/shuma/SDD.md

modules/shuma/ — Runtime de espacios aislados (era shipote)

Propósito. Cada Workspace = un proceso aislado (namespaces + cgroups + capabilities filtradas) que expone un wire protocol tipado. El daemon es dueño de los workspaces; los clientes (cli/shell/gateway) hablan postcard sobre Unix socket.

Crates

crate	tipo	rol
shuma-card	lib	Card del daemon + spec del Workspace
shuma-protocol	lib	Wire types: requests/responses + framing
shuma-discern	lib	Lookup de daemon vía broker brahman
shuma-core	lib	Pipeline: parse spec → encarnar → supervisar → persist
shuma-intent	lib	Intenciones, grafo de sesión y libro de macros
shuma-line	lib	Análisis de la línea de comandos: lexer bash, clasificación, pipeline, autocompletado, LineState editable — agnóstico (GUI/TUI)
shuma-session	lib	WorkSession: cwd (= identificador de aislamiento), historial de comandos y grupos reutilizables
shuma-exec	lib	Ejecución de comandos con salida en streaming (stdout/stderr línea a línea por canal)
shuma-sysmon	lib	Muestreo de CPU/memoria con historial para los monitores
shuma-shell-render	lib	Layout del lienzo de intenciones (legado del grafo)

App: apps/shuma-shell — el shell GPUI: input inteligente (shuma-line), ejecución real con streams (shuma-exec) volcada al panel central, sesión de trabajo con cwd/aislamiento (shuma-session), monitores con curva (shuma-sysmon) y divisores arrastrables. Los crates son agnósticos → un futuro shuma-shell-tui los reusaría sin cambios.

sandokan vs. shuma-exec

sandokan orquesta Cards de brahman (entidades aisladas y supervisadas) y es poll-based por diseño. El shell ejecuta líneas de shell ad-hoc y necesita ver la salida fluir → eso es shuma-exec. Dos capas distintas, a propósito; un comando que lance un módulo brahman podría enrutarse por sandokan más adelante.

Dependencias

• shuma-core ← init/ente-incarnate (encarnación real).
• shuma-protocol ← protocol/brahman-card.
• Apps: shuma-daemon (dueño), shuma-cli, shuma-shell (GUI), shuma-gateway (HTTP/JSON ↔ postcard).

Docs

Documentación completa en crates/modules/shuma/docs/:

• ARCHITECTURE.md — diseño + flow
• CLI.md — referencia del cli
• DEVELOPMENT.md — guía de contribución
• RECIPES.md — specs ejemplo de Workspace

Estado

LOC 6,907. Backend completo (daemon + cli funcionales). Tests sobre discern + protocol. 14 TODOs en core (supervisión avanzada). Ver docs/changelog/shuma.md.