brahman/docs/PLAN_MACRO.md

PLAN MACRO — Brahman Ecosystem

Fecha de cierre del plan input: 2026-05-19 Estado: plan compilado, pendiente de ejecución.

---

0 · Resumen ejecutivo

• 21 módulos totales: 12 existentes + 9 nuevos planeados + 1 rename pendiente.
• 6 servicios compartidos (libraries horizontales) que sostienen a los módulos de dominio.
• ~60,000-110,000 LOC de código nuevo proyectado (charka domina con su parser COBOL).
• Plazo realista: 4-8 meses con AI assistance + paralelismo agresivo (charka extiende el cronograma a ~12-18 meses).
• Filosofía consolidada: modularidad horizontal, separabilidad UI, sin daemons supremos, todo a través de Cards.

---

1 · Inventario completo

Infraestructura (capa de soporte)

módulo	estado	rol
protocol/	existe (7,278 LOC)	contratos canónicos + routing
init/	existe (4,301 LOC)	PID 1 + encarnación Linux
runtime/	existe (3,418 LOC)	bus + cas + wasm + brain
compat/	existe (3,435 LOC)	shims D-Bus systemd

Servicios compartidos (libraries horizontales)

servicio	estado	rol	consumidores
sandokan	nuevo	orquestador library (LocalEngine + DaemonEngine + RemoteEngine + auto())	shuma, nahual, matilda, ssh-mode admin, todos los binarios que ejecuten Cards
sandokan-lifecycle	extraer de shuma	TTL + restart + quota + drain + snapshot	shuma, matilda Ghost, charka-shadow, carmen, yachay
discovery-dht	nuevo	DHT library agnóstica sobre brahman-net	minga (código), card-discovery (Cards), ágora (Personas), tinkuy (futuro)
transport-ssh-multiplex	nuevo	russh + canales paralelos + reconexión silenciosa	sandokan::RemoteEngine, matilda LinkerSSH
dime	nuevo	embeddings multi-backend (cohere/bge/mini/fastembed); daemons coexisten por modelo	chasqui, akashi, charka-semantic, takiy-ai, apu (futuro)
card-discovery	nuevo	búsqueda Cards local + DHT (sobre discovery-dht)	nahual-shell (card-browser widget), ágora

Módulos de dominio

Existentes:

módulo	estado	LOC aprox	pendientes
chasqui	rename de akasha	4,395	rename mecánico + migrar a dime + tests cluster
minga	existe	5,091	minga-vfs (FUSE proyección código) + integración discovery-dht
nahual	existe	15,968	card-browser widget + separabilidad widgets/lib
pineal	existe	~4,000	6 stubs (polar, heatmap, treemap, flow, mesh, export)
nakui	existe	7,063	mantenimiento + docs morfismos
shuma	existe	6,907	extraer lifecycle + tap a tee(2)/splice
gioser	existe	2,535	estable
pluma	existe	178	AST con inline elements
vista	existe	530	estable
barra	existe	280	estable
cosmobiologia	existe	21,502	tests canvas/tree + roadmap GR/FFT/3D/rectificador

Nuevos:

módulo	rol	LOC aprox proyectada
carmen	compositor Wayland (smithay + ente-incarnate sandbox + delegación de regiones)	8,000-12,000
akashi	notes app con ECS + 4 lentes + gravedad semántica + Susurros	10,000-15,000
charka	transpilador COBOL→Rust + runtime determinista + shadow validator	25,000-50,000
matilda	administrador servidores + vhosts + Docker (con Ghost remoto)	6,000-9,000
takiy	composición musical (fundsp + ort + canvas)	5,000-8,000
dominium	simulador psicológico campo medio + render isométrico CPU	3,000-6,000
yachay	notebooks computacionales reproducibles (integración cross-módulos)	5,000-9,000
ágora	identidad humana federada + attestations + grafo + negociación	6,000-10,000

Backlog (5 + 4 honorable mentions):

nombre	rol breve
rimay	traducción memoria + lenguas indígenas
yuyay	spaced repetition + flashcards
apu	AI personal soberana (LoRA local sobre datos propios)
tinkuy	foros federados semánticos
nutu	bóveda historia clínica personal encriptada
mama-pacha	citizen-science ambiental
willay	mensajería E2E P2P
inti	energy management solar
kawsay	time tracking semántico

---

2 · Grafo de dependencias críticas

                    ┌─────────────────┐
                    │   protocol/     │  Cards + handshake + broker + net + sidecar
                    └────────┬────────┘
                             │
        ┌────────────────────┼────────────────────┐
        ↓                    ↓                    ↓
   ┌─────────┐         ┌──────────┐         ┌──────────┐
   │  init/  │         │ runtime/ │         │  compat/ │
   └────┬────┘         └────┬─────┘         └──────────┘
        │                   │
        │ ente-incarnate    │ brain-split: rules, cognitive, audit
        │ (+ pivot_root,    │ ente-cas, ente-bus, ente-wasm
        │   overlayfs)      │
        │                   │
        └──────────┬────────┘
                   │
                   ↓
            ┌──────────────────┐
            │   sandokan       │ ← lifecycle (extracted de shuma)
            │   (orchestrator) │   transport-ssh-multiplex
            └────────┬─────────┘
                     │
        ┌────────────┼───────────────────────────────┐
        ↓            ↓                               ↓
   ┌─────────┐  ┌──────────┐                  ┌─────────────┐
   │ shuma   │  │  carmen  │ (delegación      │ discovery-  │
   │ matilda │  │  Wayland │  via wl_subsurf) │   dht       │
   │ charka- │  │          │                  └──────┬──────┘
   │ shadow  │  └────┬─────┘                         │
   └─────────┘       │                  ┌────────────┼────────────┐
                     │                  ↓            ↓            ↓
                     │            ┌──────────┐ ┌──────────┐  ┌────────┐
                     │            │  minga   │ │   card-  │  │ ágora  │
                     │            │ (código) │ │discovery │  │(Pers.) │
                     │            └──────────┘ └─────┬────┘  └────────┘
                     │                               │
              ┌──────┼──────┐               ┌────────┘
              ↓      ↓      ↓               ↓
          ┌─────────────────────────────────────────┐
          │  nahual-shell  (card-browser + launcher)│
          └─────────────────────────────────────────┘

                            ┌────────────┐
                            │   dime     │ (multi-backend embeddings)
                            └─────┬──────┘
                                  │
              ┌──────────┬────────┼────────┬──────────┐
              ↓          ↓        ↓        ↓          ↓
          ┌─────────┐ ┌────────┐ ┌────────┐ ┌──────┐ ┌──────┐
          │ chasqui │ │ akashi │ │ charka │ │takiy │ │ apu  │
          │ migrar  │ │ 384d   │ │1024d   │ │audio │ │futuro│
          └─────────┘ └────────┘ └────────┘ └──────┘ └──────┘

                              ┌──────────┐
                              │ yachay   │ embebe todos los demás:
                              │(integ.)  │ pineal, dominium, takiy,
                              └──────────┘ charka, akashi, chasqui

---

3 · Plan por fases

Fase A · Foundations cleanup (semanas 1-2)

Pre-requisitos antes de meter código nuevo. La mayoría paralelizable.

#	item	bloquea	tiempo
#24	Rename akasha → chasqui	claridad de naming downstream	1 día
#13	Split brain en brain-rules + brain-cognitive + brain-audit	sandokan, ágora	3-5 días
#14	Unificar loader en brahman-cards	reduce duplicación	1-2 días
#16	Promover lifecycle a sandokan-lifecycle	sandokan, matilda, charka-shadow, carmen	4-7 días
#19	pivot_root + overlayfs en ente-incarnate	carmen, matilda Ghost, sandokan completo	4-7 días
#20	transport-ssh-multiplex	sandokan::RemoteEngine, matilda	3-5 días

Trabajo paralelo posible: 3-4 tracks. Estimación realista: 2 semanas.

Fase B · Core libraries (semanas 2-5)

Servicios compartidos que sostienen aplicaciones.

#	item	depende de	tiempo
#15	sandokan (LocalEngine + DaemonEngine + RemoteEngine + auto)	Fase A	1-2 semanas
#22	dime (4 backends + daemon multi-instancia)	(independiente)	1-2 semanas
#28	discovery-dht (library) + card-discovery	brahman-net	1-2 semanas
protocol	Extender CardKind con Person/Community/Alliance/Institution	(independiente)	1-2 días

Paralelizable. Estimación realista: 3 semanas.

Fase C · Apps standalone (semanas 4-12, paralelo)

Módulos de dominio que pueden empezar cuando sus deps de Fase B estén estables.

#	módulo	depende de	LOC	tiempo
#27	dominium	(mayormente independiente)	3-6K	3-4 semanas
#26	takiy	dime (instancia ort)	5-8K	4-6 semanas
#23	akashi	dime (instancia 384d), separabilidad UI	10-15K	6-10 semanas
#21	matilda	sandokan-lifecycle, ente-incarnate enhanced, transport-ssh	6-9K	5-8 semanas
#29	carmen	ente-incarnate enhanced, sandokan, ente-logind-compat	8-12K	8-12 semanas
#31	ágora	CardKind extension, discovery-dht, brain-audit	6-10K	5-8 semanas

Paralelizable hasta 4-6 tracks simultáneos. Estimación realista: 10-12 semanas.

Fase D · Charka (paralelo, multi-mes)

#	módulo	tiempo
#17	charka — parser COBOL completo + IR + semantic + runtime BCD + shadow + codegen	6-12 meses

Outlier por la complejidad del parser COBOL completo (CICS + SQL embedded + dialectos IBM Enterprise). Corre en paralelo con Fase C pero NO bloquea otras cosas.

Fase E · Yachay e integración cross-módulo (semanas 12-18)

#	item	depende de	tiempo
#30	yachay — notebooks reproducibles	pineal stubs cerrados, dominium estable, takiy estable, charka mínimo viable, akashi base, chasqui migrado	4-6 semanas
#25	Aplicar separabilidad UI retroactiva donde bloquee	(cuando se necesite)	1-3 semanas

Yachay es el módulo más integrador; tiene sentido al final cuando todos sus embeds están maduros.

Fase F · Roadmap previo a estabilizar (paralelo throughout)

Items del ROADMAP.md original (de docs/) que conviven con las fases nuevas:

• Cobertura tests cosmobiologia-canvas/tree (5,145 LOC sin tests)
• Cobertura tests chasqui-cluster (k-means)
• Cerrar 6 stubs de pineal (polar/heatmap/treemap/flow/mesh/export)
• minga-vfs (FUSE proyección de código)
• TODOs concentrados: brain-* (post-split), handshake fase 4, shuma supervision avanzada
• Compat avanzado systemd (Inhibit, SetVariable, MachineImage)
• Cosmobiología roadmap (GR + FFT + 3D + rectificador)

Suma estimada: 4-6 semanas continuas distribuidas entre Fases A-E.

Fase G · Backlog (post-Fase E si alcanza)

Los 5 + 4 honorable mentions. Cuando el monorepo esté maduro y haya capacidad sobrante.

---

4 · Cronograma agregado

   sem 1-2   sem 2-5    sem 4-12          sem 12-18    sem 18+
   ├Fase A──►
            ├Fase B────►
                       ├Fase C ──parallel─────►
                                              ├Fase E──►
                       ├Fase D ──charka (multi-mes)────────────►
            ├Fase F (cobertura tests + stubs cosmo/pineal)─────►
                                                       ├Fase G─►

Tiempo estimado a v1 funcional:

• Sin charka: ~4-5 meses
• Con charka completo: ~6-12 meses (depende del parser COBOL)
• Con backlog y polish: ~12-18 meses

Con paralelismo agresivo (3-5 tracks simultáneos asistidos por AI): factor 1.5-2× de aceleración.

---

5 · Critical path (camino crítico)

El camino más largo de dependencias que define el plazo mínimo:

A: rename + brain split + lifecycle + pivot_root  (2 sem)
    ↓
B: sandokan + dime + discovery-dht                (3 sem)
    ↓
C: carmen + ágora                                  (8-12 sem)
    ↓
E: yachay                                         (4-6 sem)
─────────────────────────────────────
TOTAL critical path:                              17-23 semanas (4-5.5 meses)

Charka corre EN PARALELO al critical path (no lo extiende) pero su propia trayectoria es ~6-12 meses.

---

6 · Paralelismos máximos posibles

Asumiendo que se quiere maximizar throughput con múltiples agentes/personas trabajando:

momento	tracks paralelos
Fase A	4 tracks: rename, brain-split+loader, lifecycle, incarnate+ssh
Fase B	3 tracks: sandokan, dime, discovery-dht
Fase C	4-6 tracks: dominium, takiy, akashi, matilda, carmen, ágora
Fase D	1 track dedicado: charka (multi-mes)
Fase E	1-2 tracks: yachay + separabilidad retroactiva
Fase F	1-2 tracks distribuidos en todas las fases (tests cobertura, stubs)

Pico simultáneo: ~6-8 tracks (mitad de Fase C, con charka corriendo aparte).

---

7 · Riesgos identificados

riesgo	severidad	mitigación
Parser COBOL completo es enorme (6-12 meses)	alta	Aceptado por usuario. Empezar charka temprano, paralelo. Considerar subset COBOL'85 puro como primer hito antes de CICS+SQL embed.
CRIU sobre Wayland no funciona out-of-box	media	Marcado como futuro en carmen. Documentar limitaciones.
Cross-platform determinism bit-exact (dominium)	alta	Plan ya incluye dep libm + BTreeMap + rand_chacha + serial reductions. CI cross-compile x86+ARM verificando hashes.
ZKP en ágora v2 es complejo (bbs-signatures)	media	v1 sin ZKP, v2 al final. Documentar limitaciones de v1.
Doble (o triple) descarga de modelos AI por falta de daemon dime	media	dime daemon multi-instancia desde Fase B. CAS para blob sharing.
Acoplo UI legacy de nahual widgets a GPUI	media	Separabilidad retroactiva en #25, aplicar solo donde bloquee.
Wayland compositor robusto requiere expertise específico (smithay)	alta	Empezar carmen con Fase 1 minimal (foot/alacritty rendering) antes de ambicionar fractal/delegación.
Sobre-ingeniería del fractal en carmen	media	"Si es forzado no, cuando sea grande sí" — explicit del usuario. NO en v1.

---

8 · Hitos verificables (acceptance criteria)

Para considerar cada fase "cerrada":

Fase A:

• cargo check --workspace verde tras rename a chasqui
• brain split: 3 crates separados, brain umbrella opcional, loader unificado
• sandokan-lifecycle extraído con tests pasando que cubren shuma's lifecycle existente
• ente-incarnate con pivot_root + overlayfs + tests (chroot básico)
• transport-ssh-multiplex con tests sobre russh

Fase B:

• sandokan auto() detecta socket y elige Local/Daemon correctamente
• dime con al menos 2 backends operativos (recomendado bge + fastembed) + daemon multi-instancia
• discovery-dht: publish + lookup funciona sobre brahman-net libp2p

Fase C (por módulo):

• dominium: tick deterministic bit-exact cross-platform; 4 lentes funcionan; CI cross-compile pasa
• takiy: latencia audio <10ms; persistencia ambos formatos
• akashi: 4 lentes implementadas; Susurros activos; storage sqlite-vss funcional
• matilda: Inspect/Diff/Apply ciclo cerrado; al menos provider Docker funcional
• carmen: arranca compositor; renderea alacritty; sandbox via ente-incarnate
• ágora: emite + verifica + revoca attestations; grafo navegable; integrado con CardKind

Fase D:

• charka: parsea COBOL'85 puro (subset). Hito intermedio. CICS + SQL después.

Fase E:

• yachay: notebook ejecutable bit-exacto-reproducible; embeds pineal+dominium+takiy probados

---

9 · Decisiones de ejecución pendientes

Antes de arrancar Fase A queda por decidir:

1. Persona dedica tiempo full-time o spaced? → afecta el cronograma absoluto.
2. ¿Cuántos tracks paralelos vas a sostener vos solo + Claude/AI assistants?
3. ¿Charka prioritario o relegado? → si lo dejás al final, ahorrás tiempo al critical path; si lo querés temprano, paralelizá desde Fase B.
4. ¿yachay como integrador o standalone? → si es integrador (recomendado), va al final; si standalone, puede empezar antes pero pierde el embed de los demás.

---

10 · Una vez aprobado este plan

Próximos pasos concretos cuando se dé la señal:

1. Empezar Fase A con rename akasha → chasqui (script reorg.py reusable, ya está en scripts/).
2. Crear branch phase-a-foundations para los refactors mecánicos.
3. Tests cobertura paralelo (Fase F) corre desde día 1.
4. Cada item completado: commit + push (política feedback_commit_push.md).
5. Actualizar docs/STATUS.md al cerrar cada fase.

---

Plan compilado. Cuando digas, arrancamos por Fase A.