# Report 0001 — unibus: servicio LAN + Fase 2 (transporte sobre el bus)

- **Fecha:** 06/06/2026
- **Autor:** Claude (Opus 4.8)
- **Ámbito:** `projects/message_bus/apps/unibus` (sub-repo `dataforge/unibus`) y `~/DataProyects/Github/agents_and_robots` (Gitea `egutierrez/agents_and_robots`)
- **Estado:** done (con un gap acotado documentado en Fase 2)

## Resumen

Dos entregas. **A)** `membershipd` pasa de proceso manual loopback a service systemd real
alcanzable por la LAN: flag `--bind` que gobierna a la vez el HTTP de control y el NATS
embebido, unit systemd-user con `Restart=always`, bloque `service:` completo y health
verificado desde la IP de la LAN. Esto desbloquea que un teléfono/PC remoto conecte al bus.
**B)** Fase 2 (branch-by-abstraction): se introduce una interfaz `Transport` + un tipo
`InboundMessage` neutral (sin mautrix), se desacoplan las firmas del core de agentes, se
implementa un `unibusTransport` sobre `pkg/client` de unibus, y un feature flag elige Matrix
vs unibus por bot. Pre-requisito cumplido: el `Frame` de unibus gana threading/reply/reaction
de forma aditiva.

Trabajo en ramas TBD: `issue/fase2-transport-service` (unibus) y `issue/unibus-transport`
(agents_and_robots). Master nunca tocado directamente.

## Cambios

### A — Servicio (unibus)

| Cambio | Archivo | Por qué |
|---|---|---|
| Flag `--bind` (default 127.0.0.1) aplicado a HTTP + NATS | `cmd/membershipd/main.go` | Un solo flag gobierna la alcanzabilidad de ambos planos; `0.0.0.0` expone a la LAN |
| `embeddednats.StartHost(storeDir, host, port)` (y `Start` backward-compatible) | `pkg/embeddednats/embeddednats.go` | Controlar la interfaz del NATS embebido sin romper playground/tests |
| systemd-user unit `Restart=always` | `deploy/unibus-membershipd.service` | Service persistente; `on-failure` NO reinicia tras un SIGTERM limpio (exit 0) — el gotcha de `sqlite_api` |
| `install.sh` idempotente + `README.md` | `deploy/` | build + symlink unit + enable/restart en un comando; operar/health documentado |
| Bloque `service:` completo | `app.md` | `systemd-user`, `restart_policy: always`, health `/healthz`, `is_local_only: false`; valida `fn doctor services-spec` |

### Pre-Fase 2 — Frame threading (unibus, aditivo)

| Cambio | Archivo | Por qué |
|---|---|---|
| Campos `ThreadID`, `ReplyTo` (omitempty) + tipo `REACT` | `pkg/frame/frame.go` | Bots de chat necesitan replies, hilos y reacciones |
| `PublishReply`, `React` (refactor de `Publish` a `publishFrame` compartido) | `pkg/client/client.go` | API de threading; la reacción viaja en el payload cifrado (confidencial en rooms E2E) |
| Tests: round-trip threaded, back-compat de wire/firma, error path, reply+react E2E | `pkg/frame/*_test.go`, `pkg/client/client_test.go` | golden + edge + error path |

Aditivo de verdad: un frame sin threading serializa **sin** las claves `thr`/`re`, así que su
wire y su firma Ed25519 son idénticos a antes → no rompe `Subscribe`/`Publish` ni los tests
existentes.

### B — Fase 2 (agents_and_robots)

| Cambio | Archivo | Por qué |
|---|---|---|
| `Transport` interface + `InboundMessage` neutral + `Select`/`FlagEnabled` | `pkg/transport/` | Seam neutral (cero mautrix) entre el core del agente y el fabric de mensajería |
| Flag `unibus-transport` (default off) | `dev/feature_flags.json` | Convivencia: con el flag ON cada bot opta in; el resto sigue en Matrix |
| `handleEvent(…, *event.Event)` → `handleInbound(…, transport.InboundMessage)` (Agent + Robot) | `agents/handler.go`, `agents/robot.go` | Quitar `*event.Event` de las firmas; `inboundToMsgCtx` es el único punto de conversión a `decision.MessageContext` |
| `RawMatrixClient() *mautrix.Client` → `Scanner() RoomScanner` | `agents/runtime.go`, `cmd/launcher/main.go` | Quitar el handle al cliente mautrix de la API pública; capability read-only |
| Listener entrega `InboundMessage` (no el evento) | `shell/matrix/listener.go` | El evento mautrix ya no cruza la frontera al core |
| `unibusTransport` + `DemoEchoHandler` (módulo Go anidado) | `shell/transportunibus/` | Implementa `Transport` sobre `pkg/client`; subjects `agent.<name>.{in,out}` |

## Verificación

### A — Servicio (evidencia ejecutable)

```
$ systemctl --user is-active unibus-membershipd.service
active

$ systemctl --user status unibus-membershipd.service   # (extracto)
Active: active (running)
 ExecStart=…/membershipd --bind 0.0.0.0

$ ss -tln | grep -E ':8470|:4250'
LISTEN 0  4096  *:8470  *:*        # HTTP control en todas las interfaces
LISTEN 0  4096  *:4250  *:*        # NATS data plane en todas las interfaces

$ curl -fsS -w " [HTTP %{http_code}]\n" http://127.0.0.1:8470/healthz
{"status":"ok"} [HTTP 200]

$ curl -fsS -w " [HTTP %{http_code}]\n" http://192.168.1.129:8470/healthz   # IP LAN
{"status":"ok"} [HTTP 200]

$ ./fn doctor services-spec | grep unibus
OK  unibus  systemd-user  8470  /healthz  unibus-membershipd.service  lucas-linux  -
```

**Cliente NATS conecta por IP LAN y publica/recibe** (worker→chat, ambos contra
`nats://192.168.1.129:4250` + `http://192.168.1.129:8470`, vía el service systemd):

```
[chat] subscribed to "proc.test.ticks"; waiting for messages
[proc.test.ticks] DGCob41a: tick 1 @ 2026-06-06T16:07:16Z
[proc.test.ticks] DGCob41a: tick 2 @ 2026-06-06T16:07:17Z
[proc.test.ticks] DGCob41a: tick 3 @ 2026-06-06T16:07:18Z
[proc.test.ticks] DGCob41a: tick 4 @ 2026-06-06T16:07:19Z
```

### Pre-Fase 2 — Frame (unibus)

```
$ cd projects/message_bus/apps/unibus
$ CGO_ENABLED=0 go build ./... && CGO_ENABLED=0 go vet ./...   # exit 0
$ CGO_ENABLED=0 go test ./...
ok  github.com/enmanuel/unibus/pkg/frame
ok  github.com/enmanuel/unibus/pkg/client
ok  github.com/enmanuel/unibus/pkg/membership
```

Tests nuevos: `TestThreadingRoundTrip` (golden), `TestNonThreadedWireBackCompat` (edge:
asegura que `thr`/`re` no aparecen en frames no-threaded), `TestUnmarshalRejectsGarbage`
(error path), `TestThreadedReplyAndReaction` (reply + reacción E2E en room cifrada ModeMatrix).

### B — Fase 2 (agents_and_robots)

Toda la compilación/test del repo `agents` se hace con `-tags goolm` (olm puro-Go) porque
`libolm` (CGO) no está instalado en esta máquina; en producción se usa `libolm`.

```
# Módulo anidado del transporte unibus (flag ON / camino unibus):
$ cd shell/transportunibus && go test -tags goolm ./...
ok  github.com/enmanuel/agents/shell/transportunibus
  # TestDemoBotOverUnibus: un user-peer publica en agent.demo.in; el bot, movido por
  # unibusTransport, recibe un InboundMessage y responde "echo: hola bus" / "pong" en
  # agent.demo.out. TestRunStopsOnContextCancel: lifecycle (error path).

# Módulo principal (flag OFF / camino Matrix sigue vivo):
$ go build -tags goolm ./...            # exit 0
$ go vet -tags goolm ./agents/ ./shell/matrix/ ./pkg/transport/   # exit 0
$ go test -tags goolm ./pkg/transport/ ./agents/
ok  github.com/enmanuel/agents/pkg/transport   # TestSelect (flag ON/OFF) + TestFlagEnabled
ok  github.com/enmanuel/agents/agents          # core decoplado compila+pasa
$ go test -tags goolm ./...                     # 26 paquetes ok, 1 FAIL pre-existente (ver gaps)
```

## Gaps / pendientes

1. **Segundo host físico real para A.** El round-trip de A se probó desde esta misma máquina
   contra su IP de LAN `192.168.1.129` (no loopback), lo que ejercita el bind `0.0.0.0`. No
   había un segundo PC/teléfono disponible para conectar desde otra máquina; como los sockets
   escuchan en `*` (todas las interfaces, confirmado por `ss`), el comportamiento desde un host
   remoto es idéntico. El agente de frontend puede confirmarlo desde el móvil.

2. **El Agent "pesado" todavía no corre sobre unibus.** Conflicto real de dependencias entre
   ecosistemas: `unibus` depende de `fn-registry`, cuyo módulo raíz exige
   `maunium.net/go/mautrix v0.28.0`, incompatible con el `shell/matrix` del repo `agents`
   (escrito para `v0.21.1`; MVS forzaría v0.28 y rompe 3 call-sites de la API mautrix). Por eso
   el `unibusTransport` vive en un **módulo Go anidado** (`shell/transportunibus/go.mod`): tira
   de la mautrix nueva transitivamente sin recompilar el código Matrix del padre, y ambos
   ecosistemas conviven. Consecuencia: el core del Agent (módulo principal) no puede instanciar
   `unibusTransport` directamente sin reintroducir el conflicto. El seam neutral
   (`pkg/transport.Transport`) sí está y el bot demo corre sobre el bus; **migrar el Agent
   completo a unibus requiere primero subir `agents` a mautrix v0.28** (migración aparte, fuera
   de alcance de esta tanda).

3. **`Scanner() RoomScanner` sigue devolviendo tipos mautrix** en sus métodos
   (`*mautrix.RespJoinedRooms`, …). El escaneo de rooms es una capability intrínsecamente de
   Matrix (enumera rooms de Matrix); la neutralización quita el handle al cliente crudo y lo
   sustituye por una interfaz read-only mínima, pero no puede ser 100% neutral porque el unibus
   no participa en ese escaneo.

4. **`libolm` no instalado** en esta máquina → el repo `agents` se compila/test con
   `-tags goolm` (olm puro-Go). En producción se usa `libolm`. Pendiente: instalar
   `libolm-dev` si se quiere validar el path libolm localmente.

5. **Test pre-existente en rojo, ajeno a este trabajo:** `shell/logger/TestCleanOldLogs` falla
   porque es dependiente de fecha (espera logs de marzo 2026 que la limpieza por antigüedad
   borra estando hoy a 06/06/2026). Ya fallaba en el baseline antes de tocar nada; no toqué
   `shell/logger`. Issue separado recomendado.

6. **Sin push a remoto.** El trabajo queda consolidado en `master` local de ambos repos; el
   push a Gitea queda para `/full-git-push` del operador.
   - `agents_and_robots`: `master` = merge `--no-ff` de `issue/unibus-transport` (commit
     `aa595f5`), build + tests verdes; rama borrada.
   - `unibus`: **condición de carrera entre dos agentes en el mismo repo.** El agente de
     frontend trabajaba en paralelo en el mismo working tree de unibus y nuestros `git checkout`
     se interleavearon: mis commits A1/A2/A3 (`--bind`, deploy, service block) acabaron
     directamente en `master`, y los de threading + bump (`2209283`, `69079d1`) cayeron sobre la
     rama del otro agente `issue/frontend-web-movil`. Como esos dos commits son lineales sobre
     mi A3 (`b2e6712`) y NO contenían trabajo del otro agente, consolidé `master` con
     `git merge --ff-only 69079d1` (sin duplicar commits, sin tocar la rama del frontend). Estado
     final: `master` de unibus contiene TODO mi trabajo (A1-A3 + threading + bump 0.3.0), tests
     `pkg/...` verdes, working tree con el WIP del frontend (mobile/playground/android/web)
     intacto. **Lección operativa:** dos agentes Claude en el mismo repo comparten HEAD/índice;
     hace falta worktrees separados (`git worktree`) o repos clonados por agente para evitarlo.