---
name: message_bus
description: "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."
tags: [messaging, nats, e2e, bus, service]
repo_url: "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.