message_bus/project.md

name, description, tags, repo_url

name	description	tags	repo_url
message_bus	Bus de mensajería unificado sobre NATS+JetStream con cifrado E2E por room (patrón megolm/olm reducido). Peers uniformes: procesos, chat humano y agentes LLM hablan el mismo protocolo.	messaging nats e2e bus service	https://gitea-dgg044oo04woo4ggcsws4gk0.organic-machine.com/dataforge/message_bus

Notas

Bus de mensajería con identidad uniforme: un solo tejido de comunicación donde cualquier participante —procesos/workers, interfaces de chat humanas, agentes LLM— es un peer de primera clase. Todos hablan el mismo protocolo y se diferencian solo por las rooms a las que se unen y por lo que hacen con lo que reciben.

Qué reemplaza

Este project sustituye dos piezas de infraestructura existentes:

• agents_and_robots (egutierrez/agents_and_robots en Gitea): plataforma Go de bots Matrix autónomos acoplada a maunium.net/go/mautrix. Su lógica de agente (pkg/{decision,personality, knowledge,memory,llm,skills,tools,orchestration,acl}) se preserva; solo cambia la capa de transporte (Matrix → este bus).
• El servidor Matrix self-hosted (Synapse) de organic-machine.com.

La integración con agents_and_robots es una fase posterior: v1 construye y valida el bus de forma autónoma (service de membresía/claves + librería cliente + peers demo).

Decisión arquitectónica

NATS (+ JetStream) como motor de transporte; una capa fina encima aporta lo que NATS no tiene: membresía de rooms, invitaciones con reparto de clave, y cifrado E2E del payload. No se construye un broker ni un protocolo propios.

Alcance v1 (decisiones acordadas)

• Solo el bus: service de membresía/claves + librería cliente Go + peers demo (worker + chat), todo arrancable con go run. Integración con agents_and_robots en fase aparte.
• Rotación de clave activa: al hacer LEAVE/KICK la clave de room K rota a un nuevo epoch y se re-reparte solo a los miembros restantes. Forward secrecy real (paridad con Matrix), no el modo "sin rotación" del documento de diseño original.
• Media en object store: los adjuntos no viajan por el bus. Se cifran y se suben a un object store; por NATS solo viaja una referencia (hash + nonce). El bus transporta mensajes, no blobs.
• NATS embebido: el service arranca un nats-server embebido con JetStream para que todo funcione con go run sin instalar nada. Flag --nats-url para apuntar a un NATS externo en producción.

Criptografía (funciones del registry, capability group e2e-messaging)

El cifrado E2E se compone de primitivas del registry, no de código inline:

• generate_identity_go_cybersecurity — par Ed25519 (firma) + X25519 (intercambio de claves).
• seal_aead_go_cybersecurity / open_aead_go_cybersecurity — ChaCha20-Poly1305 sobre el payload.
• seal_key_box_go_cybersecurity / open_key_box_go_cybersecurity — sealed box anónimo (nacl/box) para repartir K a un invitado por su pubkey X25519.
• sign_ed25519_go_cybersecurity / verify_ed25519_go_cybersecurity — firma por-mensaje.

Apps

• apps/unibus/ — el bus completo: librería cliente (pkg/client), service de membresía/claves (cmd/membershipd, tag service), object store, y peers demo (cmd/worker, cmd/chat).

Terminología: peer, bot, bot agente

Convención única del proyecto (reemplaza la antigua distinción "agentes" vs "robots" de agents_and_robots):

• peer — cualquier participante del bus. Es la unidad del protocolo: todos los peers son iguales y se diferencian solo por las rooms a las que se unen y por lo que hacen al recibir un mensaje. Un peer puede ser un proceso, un humano o un bot.
• bot — término único para todo peer automatizado (programático), tenga o no un LLM. Sustituye la dualidad previa donde un peer sin LLM se llamaba "robot" y uno con LLM "agente". A partir de ahora todos los participantes automatizados son bots.
• bot agente (abreviado "agente") — un bot que contiene un LLM en su lógica de decisión. Es un subtipo de bot, no una categoría aparte.
• humano — peer con una persona detrás, que usa un cliente de interfaz (hoy el playground web). No es un bot.

Implicación para la Fase 2 (migración de agents_and_robots): los dos tipos actuales Agent (agents/runtime.go) y Robot (agents/robot.go) se unifican conceptualmente bajo bot; un bot agente es simplemente el bot cuyo handler invoca un LLM.