@nyx5/nyx5 0.7.0 → 0.9.0

package/docs/ARQUITECTURA.md

@@ -188,6 +188,358 @@ La clave pública sale de `data/sigo.uk/domain.json` (`keys[0].sig`). Sin DNS, e
 
 Cada `/inbound` hace: dos GET cacheados (tarjetas, 5 min), dos verificaciones Ed25519 (microsegundos), una escritura. Un solo proceso Node maneja miles de sobres por minuto. El costo real está en el almacenamiento y en los reintentos hacia dominios caídos; el backoff exponencial y el tope de 3 días lo acotan.
 
+### 4.6 Asistentes de la casa y qa@ (NX-606)
+
+Un asistente es una dirección que contesta sola con la API de Anthropic (`src/correo/asistente.js`),
+dentro de un tope mensual en dólares (`budget_usd`) que se calcula del `usage` real. Hay dos modos de
+alta, los dos por `POST /admin/assistants` con `Bearer <admin>`:
+
+- **Delegado** (el asistente de Sigo): `{ local, keys, config }` sobre una dirección delegada de sólo
+  mensajes que ya existe. No tiene cuenta en el Libro.
+- **De sistema** (qa@): `{ local, keys, config, system: true }`. La casa registra `<local>@<casa>` como
+  dirección raíz propia (sin delegación), guarda `keys` en la bóveda (`NYX5_VAULT_KEY`), publica la
+  tarjeta con `custody: { keys: "house", via: "assistant" }`, buzón `open`, sin regalo de bienvenida,
+  y por ser raíz **sí** tiene cuenta en el Libro: recibe `pay`. Nombres del protocolo (`libro`,
+  `verifica`, `tareas`, `postmaster`) se rechazan; `qa` está reservado para todos y sólo entra por aquí.
+
+Cuerpo exacto del alta de `qa@` (las llaves se generan con `generateKeys()` de `src/nucleo/crypto.js`
+y NO se guardan fuera de la bóveda; el script que las genera y hace el POST vive fuera del repo):
+
+```json
+{
+  "local": "qa",
+  "system": true,
+  "keys": { "sig": "<pub>", "sigPriv": "<priv>", "enc": "<pub>", "encPriv": "<priv>" },
+  "config": {
+    "owner": "nicholas@nyx5.com",
+    "model": "claude-opus-5", "effort": "high", "max_tokens": 8000, "budget_usd": 30,
+    "persona": "<persona de Spec>",
+    "seal": true,
+    "price_tokens": 400,
+    "gate": true, "gate_price_tokens": 400, "gate_abstain_tokens": 200,
+    "persona_gate": ""
+  }
+}
+```
+
+`persona_gate` vacío usa `PERSONA_GATE` (la del código). Respuesta `201` con `address`, `custody` y la
+config (las personas se devuelven como largo, no como texto). `GET /admin/assistants/qa` muestra
+`system`, `owner`, precios, gasto del mes y pendientes; `PUT .../config` cambia precios y personas sin
+volver a dar de alta; `POST .../pause` y `.../resume`. Sin `ANTHROPIC_API_KEY` el asistente existe y
+no llama a nada.
+
+Cómo se cobra: el cliente paga por adelantado con `pay { to: "qa@<casa>", amount, concept }` (op del
+Libro, firmada por él). Al llegar una pedida, crédito = pagos de ese cliente en el diario − consumido
+(kv `asistente-credito`, clave `<local>:<cliente>`). Si no alcanza, la respuesta lo dice y **no se
+llama a la API**. Si alcanza, se reserva antes de llamar (si la API falla, se devuelve), y el pie de
+la respuesta lleva `cobrado: N tokens · crédito restante: M`. El dueño (`owner`) y sus delegados no
+pagan. Gate (`application/nyx5.gate+json`) exige que el hash del contrato esté sellado en la notaría de
+la casa antes de gastar, y devuelve un veredicto JSON firmado por la casa; una abstención cobra
+`gate_abstain_tokens`. Qué NO cubre: Gate no descarga `delivery.url` y no exige que el sello sea del
+cliente (lo anota en `sealed_by`).
+
+### 4.7 ideas@: el buzón automático de vacaciones (14-sep-2026)
+
+`src/correo/ideas.js`. Un agente de sistema que RECIBE, GUARDA y CONFIRMA, y NUNCA EJECUTA. Corre desde
+el reloj programado, sin el Mac y sin la API de Anthropic. Se enciende por casa con `NYX5_IDEAS=on`
+(exige `NYX5_VAULT_KEY`: su llave vive en la bóveda). Alta, una vez, con `Bearer <admin>`:
+
+```
+POST /admin/ideas
+{ "owner": "nicholas@nyx5.com",
+  "allow": ["nico@nyx5.com", "claude.nico@nyx5.com", "code.nicholas@nyx5.com"],
+  "keys": { "sig": "<pub>", "sigPriv": "<priv>", "enc": "<pub>", "encPriv": "<priv>" } }
+```
+
+Respuesta `201` con `address`, `custody` y la lista (el dueño entra siempre). Las llaves se generan con
+`generateKeys()` y no se guardan fuera de la bóveda. El mismo POST **sin `keys`** cambia la lista
+(`200`); con `keys` sobre un buzón existente da `409`: la llave no se reemplaza por esta puerta. A cada
+dirección de la lista que sea de la casa y filtre por lista (un Claude conectado) se le agrega `ideas@`
+para que la confirmación pueda volver; sin eso rebotaría en silencio.
+
+Cada tick: sobre firmado de la lista → número `IDEA-###` (`kvIncrement` en `nyx5_kv`, ns `ideas`, clave
+`_n`; un turno por sobre en `ideas-turno` y un número por sobre en `sobre:<id>`) → registro `n:<000001>`
+→ confirmación cifrada al remitente (texto fijo en `CONFIRMACION`) → acuse. `GET /ideas` (firma del
+dueño o `Bearer <admin>`) devuelve el registro ordenado; el contenido no está ahí: sigue cifrado en el
+buzón, y el remitente lo relee en su conversación con `ideas@`. `test/ideas.test.js` comprueba por
+inspección de la fuente (con mutantes) y espiando la casa durante el tick que el módulo no tiene otra
+salida que esa confirmación.
+
+Revisión adversarial antes de desplegar (14-sep-2026, `scripts/revision-ideas/`), lo que cambió:
+- **La puerta de ideas@** (`puertaIdeas`, consultada por `inbound` después de la política general): sólo
+  la lista. Un `intro` o un aval con fianza rebotan (antes entraban y el tick los cerraba: 2.000 intros
+  de 20 extraños = 2 MB en el buzón, que no se borra nunca). Un correo a `ideas@` se rechaza en la
+  puerta (rebote SMTP): antes entraba con `From:` de la lista y se tragaba en silencio.
+- **Cupo diario por remitente**: 200 ideas o 5 MB por día UTC (`nyx5_kv`, ns `ideas-cupo`, vence al día
+  siguiente). Medido: una dirección de la lista metía 112 MB por minuto. Lo que sobra rebota con motivo,
+  403 (permanente): un 429 dejaba la cola de la otra casa reintentando un día entero. NO protege el
+  resto de la casa: cualquier buzón `open` sigue aceptando 1 MB × 120 por minuto por dirección.
+- **El registro no depende del orden de escritura**: si el reloj cae entre asignar el número y escribir
+  `n:`, el reintento (15 min) escribe el registro con el mismo número antes de confirmar. Antes confirmaba
+  con un registro de respaldo y la idea quedaba fuera de `GET /ideas`.
+- **`GET /ideas` pagina**: `{ total, count, ideas, next }`, 1.000 por página, `?after=<n>`. Antes cortaba
+  en 1.000 en silencio y `total` decía 1.000.
+- **La guardia de la fuente es una lista CERRADA** de miembros permitidos de `est`, `est.store` y
+  `agente`: cuatro mutantes pasaban la lista de prohibidos (`putMail` a otro buzón, `_push`, `emailOut`,
+  `inbound` directo). Y en vivo, una pasada de `atenderIdeas` con espías sobre toda la superficie que
+  puede sacar algo: la única llamada permitida es `/outbound` de `ideas@` al remitente.
+- Trampa de las pruebas: en Node el adaptador dispara un `tick()` COMPLETO tras cada petición (en el
+  edge va con `programado: false`), así que una llamada directa a `atenderIdeas` compite con él; las
+  pruebas que observan una pasada apagan `casa.tick` mientras dura.
+
+### 4.8 Agentes vivos: adoptar una dirección y darle manos (26-oct-2026)
+
+`src/correo/acciones.js` + `_adoptarAsistente` / `_quitarAsistente` en la estafeta,
+`test/vivos.test.js`, SPEC §23c-bis. Es lo que permite que `rosetta@`, `norte@` o `sigo@` — que YA
+existen, con su historial y su tarjeta — piensen y actúen desde la casa, sin el Mac de Nicholas.
+
+**Adoptar** (dirección que ya existe, raíz, no delegada). La llave privada se pide a su dueño una vez
+y queda en la bóveda; la tarjeta pasa a declararlo.
+
+```
+POST /admin/assistants           Authorization: Bearer <admin>
+{ "adopt": true, "local": "rosetta",
+  "keys": { "sig": "<pub, el de su tarjeta>", "sigPriv": "<priv>", "enc": "<pub, el de su tarjeta>", "encPriv": "<priv>" },
+  "config": { "budget_usd": 5, "model": "claude-opus-5", "effort": "medium", "tools": true,
+              "owner": "nicholas@nyx5.com", "persona": "<quién es y qué hace>" } }
+```
+
+`201` con `address`, `custody` (`keys: house`, `via: assistant`) y `enabled: false`. **Nace apagada**:
+nadie se despierta solo por haber sido adoptado. Se enciende aparte, y así queda registrado cuándo:
+
+```
+PUT  /admin/assistants/rosetta/config   { "enabled": true }
+PUT  /admin/assistants/rosetta/knowledge { "texto": "<lo que tiene que saber>" }
+GET  /admin/assistants/rosetta           -> enabled, adopted, tools, budget_usd, spent_usd, pending
+DELETE /admin/assistants/rosetta         -> quita el cerebro; la dirección sigue VIVA
+```
+
+Qué falla cerrado, y por qué: un **delegado** no se adopta (`409` nombrando al dueño: su llave la
+controla él, y la casa no se la toma por detrás); una dirección ya bajo custodia de la casa por otra
+vía — el buzón de ideas, un Claude conectado — no se pisa (`409` nombrando la vía); una que no existe
+es `404`; las llaves tienen que ser las de ESA tarjeta y probar posesión (`400`).
+
+**Las manos** (`tools: true`): cinco herramientas, lista CERRADA, ejecutadas por la casa con la llave
+del propio agente y por las mismas puertas que todos (`/outbound` → `/inbound`), dentro del turno y
+del mismo tope en dólares. `nyx5_enviar` (sólo a su lista o su dueño, nunca a un grupo, a una
+dirección de sistema o a sí misma; 5 por turno), `nyx5_buscar`, `nyx5_historial`, `nyx5_notarizar` y
+`nyx5_recordar` (1 por turno, nunca antes de 5 minutos). **Nada que mueva dinero**: la lista es
+cerrada, el despacho es una tabla congelada a la que se llega por `Object.hasOwn`, y
+`test/vivos.test.js` inspecciona la fuente con una lista de permitidos y la muta (27 mutantes, 27
+gritos). Lo que pida el modelo y no esté se contesta como que no existe y el turno sigue.
+
+Tres cosas que hay que saber para no romperlas:
+- **El `task` ya no es un agujero de silencio.** Un tipo que el asistente no atiende se contesta
+  (`NO_ATIENDE`) y se confirma. Los únicos sobres que se cierran sin contestar son el recibo de un
+  agente de sistema, el que llegó por un grupo, el de un remitente que la lista no eligió (un `intro`
+  de 4 KB o un avalado, §9) y el de un buzón que cobra estampilla. Ese último es el agujero del
+  14-sep por otra puerta: **el rebote también es un sobre, y la estampilla la paga quien manda**, así
+  que a un buzón con estampilla no se le rebota (`cobraEstampilla`). El correo sin firma sigue
+  quedando pendiente a propósito: contestarle iría a la pasarela, y cerrarlo lo esconde.
+- **Un recordatorio propio despierta al agente y NO se contesta.** Contestarse deja otro sobre propio
+  y el turno siguiente lo atiende: bucle. Hay cupo de `CUPO_DESPERTAR` despertares por día UTC
+  (`nyx5_kv`, ns `asistente-despertar`), y el aviso de «llegué a mi tope» tampoco se manda a sí misma.
+- **Un sobre a sí mismo pasa su propia política de buzón** (`politica.js`). Antes `recordar` rebotaba
+  contra su propia lista blanca — `nyx5_remind` era decorativo en todo buzón por lista — y un buzón
+  con estampilla se cobraba a sí mismo. Una lista, una prueba de trabajo o una estampilla defienden de
+  OTROS; esto no abre nada, porque sólo quien tiene esa llave puede firmar como esa dirección.
+
+**Lo que entra y lo que cuesta** (revisión adversarial del 26-oct, `scripts/revision-vivos/`).
+`LIMITES_ENTRADA` en `asistente.js` es UNA constante: `pregunta: 40_000` caracteres y `turnos: 6`
+cartas de historial, cada una recortada al mismo tope. Una pregunta más larga NO llama a la API: se
+contesta cuánto es el máximo y se confirma. Medido antes: cuatro preguntas de 100 KB mandaron 102,
+200, 297 y 395 KB a la API (el costo crece con el CUADRADO); después, cada turno se estabiliza en
+~121 KB (≈US$0,16 de entrada a precio de `claude-opus-5`) y no crece con los turnos.
+
+**Los contadores durables** (`nyx5_kv`), que son el único freno real de un asistente que corre solo:
+
+| ns | clave | qué es |
+|---|---|---|
+| `asistente-gasto` | `<local>:<mes>` | gasto del mes en **micro-dólares**, sumado con `kvIncrement` (atómico) |
+| `asistente-gasto` | `<local>:<mes>:n` · `:avisado` | llamadas del mes · el aviso al dueño, reservado con `kvPutIfAbsent` |
+| `asistente-envios` | `<local>:<día>` | envíos del día (`CUPO_ENVIOS_DIA`, 100), cobrados al mandar |
+| `asistente-despertar` | `<local>:<día>` | despertares propios del día (`CUPO_DESPERTAR`, 24), cobrados al TOMAR el turno |
+
+Dos reglas que nacieron de defectos medidos, y no se tocan: **un contador de plata no se lee-suma-escribe**
+(dos relojes hicieron dos llamadas a la API y quedó anotada UNA: un tope que cuenta de menos no es un
+tope), y **un cupo se cobra al usarlo, no al mirarlo** (se contaban 8 despertares por 4 recordatorios, y
+los que quedaban fuera de `maxPorTick` también pagaban: el agente dejaba de despertar sin haber
+despertado). La forma vieja del gasto (`{ usd, llamadas }`) se convierte sola la primera vez que se
+lee, así que el mes en curso de `qa@` y `sigo.nicholas@` no se reinicia al desplegar.
+
+**Volver a poner el cerebro después de un `DELETE`**: la re-alta de un asistente de SISTEMA da `409`
+(el nombre ya está registrado). La vía es la **adopción** (`adopt: true` con las llaves de esa
+tarjeta), y vuelve apagada. El crédito consumido y el gasto del mes NO se reinician: el `DELETE` no es
+una forma de volver a empezar la cuenta.
+
+### 4.9 Ejecutores: el webhook de la casa cableado al CI del proyecto (27-oct-2026)
+
+`src/correo/ci.js` (el lado casa) + `src/puentes/ejecutor.js` (el lado job) + `examples/ci/nyx5-ejecutor.yml`
+(el workflow que se copia al repositorio), `test/ci.test.js`, SPEC §23f. Es la otra mitad de NX-412:
+§4.8 despierta a los agentes que **piensan**; esto despierta a los que **ejecutan**. Medido con la
+fábrica de Rosetta: 7 de sus 8 roles trabajan sobre archivos y no caben en un Worker.
+
+**Alta** (la dirección ya existe; nace APAGADA):
+
+```
+POST /admin/executors            Authorization: Bearer <admin>
+{ "local": "carta.rosetta", "provider": "github", "repo": "OWNER/REPO",
+  "event_type": "nyx5", "owner": "nicholas@nyx5.com", "cupo_dia": 20,
+  "token": "<PAT con Contents: read and write sobre ese repo>" }
+
+PUT  /admin/executors/<local>    { "enabled": true }          enciende, rota el token, cambia el cupo
+GET  /admin/executors            lista; GET /admin/executors/<local> agrega los sobres despachables
+POST /admin/executors/<local>/dispatch   vuelve a intentar lo AGOTADO (no lo que ya corrió)
+DELETE /admin/executors/<local>  quita el ejecutor Y el token
+```
+
+**El token**. Va cifrado en la bóveda (`NYX5_VAULT_KEY`, AAD `ci:<local>`), de sólo escritura: ninguna
+lectura lo devuelve, se muestran los últimos 4. Se ROTA, no se recupera. Un cuerpo de error del
+proveedor que lo repita se redacta antes de guardarse o registrarse.
+
+**En el repositorio** hacen falta dos cosas y nada más: el workflow copiado a
+`.github/workflows/nyx5-ejecutor.yml` y el secret `NYX5_KEY` con el contenido TAL CUAL del archivo que
+da `nyx5 keygen` (`{ address, estafeta, keys: {…} }`), o un MAPA `{ "<dirección>": <ese archivo> }`
+cuando el mismo repositorio es la casa de varios roles. La llave del rol **no pasa por la casa**: la
+casa guarda el token de CI, el repositorio guarda la llave de la dirección, y cada lado tiene sólo lo
+suyo. `llaveDe` acepta las tres formas; que esperara sólo la plana fue un defecto cazado mirando un
+archivo de verdad de la fábrica y no el ejemplo de la prueba.
+
+**Lo que hay que saber para no romperlo**
+
+- **La casa avisa y no cierra el sobre.** Confirmarlo sería prometer que alguien lo tomó. El sobre
+  queda pendiente hasta que el ejecutor conteste; el reloj redespacha hasta `INTENTOS` (3) con espera
+  creciente (1, 5 y 25 minutos) y después le escribe al `owner` nombrando el sobre, el repo, la razón
+  y la ruta para reintentar. Es la lección del `task` que estuvo seis semanas callado: lo que no se
+  sabe hacer se dice, nunca se calla.
+- **Un sobre lo contesta UNO.** Cerebro o ejecutor, nunca los dos: el `409` va en los dos sentidos.
+- **Un ENCARGO por grupo SÍ despierta (29-oct-2026).** Hasta ese día un sobre de grupo no despertaba
+  ni a un cerebro ni a un ejecutor, con esta razón del 26-oct: «un grupo es un camino que la lista del
+  buzón no eligió». Cierto para quince miembros conversando, FALSO para un encargo con plazo: el
+  29-oct el paquete Santander salió del Claude web de Nicholas a `g.rosetta@` —plazo lunes, reunión
+  el martes— y no despertó a nadie. El canal que uno usa para repartir trabajo era el único que no
+  podía despertar. Ahora despierta si el sobre DECLARA la intención: tipo `task`, o proyecto Y rol.
+  `esEncargo`/`porGrupo` viven en `asistente.js` y `ci.js` las IMPORTA: dos definiciones se separarían
+  y entonces el mismo sobre despertaría a un cerebro y no a un ejecutor. Lo cruza una prueba.
+  La respuesta va a QUIEN ENCARGÓ, nunca al grupo. El tope en dólares sigue siendo del dueño y se
+  gasta por cada cerebro del grupo: hoy son dos en la casa y ninguno está en un grupo.
+- **El candado del turno lleva la DIRECCIÓN, no sólo el sobre** (mismo día, defecto de antes). Un
+  sobre con varios destinatarios —y todo sobre de grupo lo es— lo contestaba UNO solo: el primer
+  reloj tomaba `asistente-turno:<id>` y los otros buzones lo veían ocupado para siempre. Ahora es
+  `<local>:<id>`, igual que el contador de fallas. Verificado por mutación: con la clave vieja, de
+  dos cerebros de un grupo contesta uno.
+- **El cupo del día es el freno de plata** y se cobra al DESPACHAR, no al mirar (el cupo de
+  despertares se gastaba sin despertar a nadie, medido el 26-oct). El reintento a mano NO lo levanta.
+- **Un turno por (sobre, intento)** con `kvPutIfAbsent`: dos isolates del edge que vean el mismo
+  pendiente arrancan UN job. La carrera no se ve corriendo el reloj dos veces en Node (el servidor
+  local serializa): se golpea el método, dos despachos concurrentes sobre el mismo almacén.
+- **El aviso se verifica antes de leer el buzón.** Un `repository_dispatch` lo lanza cualquiera con el
+  token del repo y el payload lo escribe quien dispara: `ejecutor recoger` comprueba la firma de la
+  casa contra `/.well-known/nyx5.json` y, si no verifica, no lee nada. Y en el workflow el aviso viaja
+  por **variable de entorno**, nunca interpolado en una línea de shell.
+- **Lo que NO cubre**: el job tiene acceso de escritura al repositorio, así que un encargo de alguien
+  de la lista puede cambiar archivos — el límite es la lista del buzón y lo que haga el paso de
+  trabajo, no el protocolo; una respuesta que el job manda y después muere antes del `ack` hace que la
+  casa redespache y el encargo se conteste dos veces (el `ack` va después del envío a propósito:
+  perder un encargo es peor que repetir una respuesta); y un proveedor nuevo es una decisión, no una
+  configuración (se le da a la casa un host al que puede mandar un token).
+
+### 4.10 El resumen en claro del aviso por correo (29-oct-2026)
+
+`EXT_RESUMEN`/`resumenDe` en `politica.js`, `summary` en `Agent.send` y en la herramienta MCP
+`nyx5_send`, y el asunto en `_notifyEmail`. `test/email.test.js` + `test/mcp.test.js`, SPEC §23g.
+
+Nicholas, 29-oct: «me llegan mails de Nyx5 pero no sé qué significan ni qué hacer con ellos». Tenía
+razón: el aviso decía `rosetta@nyx5.com wrote to you on Nyx5 (project santander)` y nada más, porque
+el cuerpo va cifrado y la casa no lo lee. Once avisos en treinta días, todos inútiles para decidir.
+Ahora el REMITENTE puede adjuntar una línea sin cifrar y la casa la pone en el asunto.
+
+**Lo que hay que saber para no romperlo**
+
+- **La línea es del remitente y la casa no la toca**: no la inventa, no la resume y no la verifica —
+  y el propio correo lo dice. Es lo que permite que exista sin romper el invariante 8.
+- **Entra a un ASUNTO de correo**, así que es texto ajeno en una cabecera: `limpio` cambia los
+  controles por espacios y colapsa, de modo que un `\r\n` no puede abrir una cabecera nueva. Tope
+  140. Verificado por mutación: con `slice` en vez de `limpio`, la prueba grita.
+- **Sin resumen, el texto del aviso queda BYTE A BYTE** como el que Nicholas aprobó el 14-sep. Una
+  mejora no reescribe en silencio lo ya acordado; lo cuida la prueba que compara el asunto exacto.
+- **Viaja en claro con el sobre cifrado**, y una prueba lo fija: si alguien lo mete dentro del
+  cifrado «para protegerlo», el aviso vuelve a no poder decir nada y el defecto no se vería.
+- **La descripción de la herramienta MCP es parte del control**: dice IN THE CLEAR, dice el tope y
+  dice qué NO poner. Es lo único que lee el agente antes de decidir qué expone. Una prueba la fija.
+
+### 4.9 Adjuntos cifrados: el almacén de objetos (NX-413, 2-nov-2026)
+
+`src/nucleo/objetos.js` + `src/correo/adjuntos.js` + la ruta `/blob/<blobId>` en la estafeta,
+`test/adjuntos.test.js` y `test/politica.test.js`, SPEC §5b. Nace de un síntoma de Nicholas: un
+agente de cowork le manda archivos a un agente de code, el de code acusa recibo del mensaje y los
+archivos no están. El campo `attachments` llevaba meses publicado en la spec y **ninguna casa
+alojaba un byte**: lo único que podía viajar eran rutas de la máquina del remitente.
+
+**Qué hace falta para encenderlo en producción** (lo hace Nicholas; la sesión NO lo hizo):
+
+```
+npx wrangler r2 bucket create nyx5-blobs
+npx wrangler r2 bucket create nyx5-blobs-b
+```
+
+y el binding en `wrangler.toml` y en `wrangler.beta.toml`:
+
+```toml
+[[r2_buckets]]
+binding = "BLOBS"
+bucket_name = "nyx5-blobs"      # en la beta: nyx5-blobs-b
+```
+
+**No hay migración de D1**: los metadatos viven en `nyx5_kv` (espacios `adjuntos` y
+`adjuntos-cupo`), que la 0006 ya creó. Mientras no exista el binding, la casa **no aloja adjuntos**
+y `/blob` contesta 503 diciéndolo; la tarjeta del dominio tampoco anuncia cupos. Eso es a propósito:
+anunciar un límite es prometer que hay dónde guardar, y esa promesa sin nada detrás es justamente el
+defecto que este ítem vino a cerrar.
+
+**Lo que hay que saber para no romperlo**
+
+- **El objeto se guarda cifrado y la casa no tiene la llave.** AES-256-GCM, una llave aleatoria por
+  adjunto, y la llave viaja en `attachments[].key` DENTRO del bloque cifrado del sobre. La primera
+  prueba de `test/adjuntos.test.js` mete una cadena testigo dentro del archivo y comprueba que no
+  aparece en el objeto crudo, ni en los metadatos, ni en el sobre del buzón, ni en el disco de
+  ninguna de las dos casas. Se escribió ANTES del código.
+- **La clave del objeto es `blobs/<uuid>`, nunca el nombre del archivo.** Un nombre trae `../` y
+  además le cuenta a la casa qué hay dentro. `ObjetosDisco` vuelve a comprobar la forma de la clave:
+  un almacén que escribe donde le digan es un traversal esperando a que alguien se confunda.
+- **El array de AFUERA es un vocabulario CERRADO** (`blob`, `bytes`) en un sobre cifrado, y una
+  clave de más se rechaza POR NOMBRE. Se aparta del invariante 7 a propósito, como `ALCANCE_MANDATO`:
+  ignorar un campo de más no es neutro cuando ese campo es `name: "balance-despido-javier.pdf"`.
+- **AAD = `nyx5:blob:<blobId>:<from>`**: un adjunto no se reusa desde otra dirección ni se hace
+  pasar por otro objeto, aunque alguien tenga la llave.
+- **La autenticación va ANTES de mirar si el objeto existe.** Si fuera al revés, `/blob` sería un
+  oráculo de existencia para cualquiera sin firma. La prueba compara cuerpo y cabeceras de un blob
+  que existe contra uno que no, sin firma, y exige que sean idénticos.
+- **Dos cupos de naturaleza distinta.** El del remitente por día UTC es de FLUJO: se incrementa antes
+  de comparar (como `puertaIdeas`) y un intento rechazado por cupo SÍ lo gasta, que es lo que corta
+  una inundación. El de la casa es de lo GUARDADO: sube al guardar y BAJA al borrar, y un intento que
+  no llega a guardar se devuelve — si no, el 1 GB se erosionaría con cada rechazo hasta bloquear a
+  todo el mundo. El tope por adjunto se comprueba antes de tocar cualquier contador: es aritmética,
+  no una carrera, y no tiene por qué gastarle el día a nadie.
+- **La retención se aplica al LEER, no sólo cuando el reloj pasa.** 30 días, o 7 desde que el último
+  destinatario lo bajó. Si el reloj se cae, un adjunto vencido sigue sin poder bajarse; el reloj
+  recupera el espacio, la puerta cumple la promesa.
+- **«Que todos confirmaron» aquí significa que todos lo BAJARON**, porque es lo único que la puerta
+  de descarga puede observar. La spec lo dice con esas palabras en vez de prometer otra cosa.
+- **No va por el conector remoto.** Allí la llave del subagente vive en la bóveda, así que la casa
+  cifraría en su nombre y el archivo pasaría por ella en claro: el mismo motivo por el que el pedido
+  de pago (NX-502) tampoco está en el remoto.
+- **Los adaptadores pasan bytes crudos** (`rx.raw`) sólo para `PUT /blob/<id>`. El tope del
+  transporte (16 MB) es mayor que el de la ruta (10 MB) a propósito: así el motivo del rechazo lo da
+  la ruta nombrando el límite real, y no el transporte con un «body too large».
+- **Lo que NO cubre, declarado**: un llamador con firma válida distingue un `blob` que existe de uno
+  que no (403 contra 404), o sea un oráculo de existencia para un uuid que ya tuvo que ver; la casa
+  sabe el tamaño, el remitente y los destinatarios de cada adjunto, porque tiene que servirlos y
+  medirlos; el `bytes` del sobre es lo que DECLARA el remitente, y la garantía real es el hash del
+  claro que comprueba el receptor; no hay deduplicación entre sobres ni vista previa; y el cupo del
+  día se cobra al aceptar, así que dos relojes a la vez pueden pasarse por uno, nunca por mucho.
+
+
 ## 5. Interoperabilidad
 
 - **MCP**: `nyx5 mcp --agent keys/x.json` expone el agente como servidor MCP por stdio. Configuración para Claude Desktop en el README. En sentido inverso, un sobre `task` con `media: application/mcp-call+json` es una llamada MCP con buzón.

package/docs/HOUSE.es.md

@@ -0,0 +1,237 @@
+# Monta tu propia casa
+
+Nyx5 es federado. Una **casa** es el correo y el libro contable de un dominio: entrega direcciones
+(`agente@tu-dominio`), guarda los buzones mientras los agentes están apagados, y lleva una
+contabilidad de doble entrada. Las casas se hablan entre iguales — no hay servidor central, y nada
+de esta guía le pide permiso a nadie.
+
+Tiene dos mitades. La primera levanta una casa en tu computador con un comando y sin cuenta en
+ningún lado. La segunda pone una en producción sobre Cloudflare. Cada comando de aquí se corrió
+antes de escribirlo.
+
+---
+
+## 1. En tu computador, con un comando
+
+Node 20 o más nuevo. Cero dependencias: no hay paso de `npm install`.
+
+```
+git clone https://github.com/Nicoiakl/nyx5
+cd nyx5
+node bin/nyx5.js estafeta --domain casa.local --port 4555 --data ./datos --admin-token la-que-se-te-ocurra --registration open
+```
+
+Eso es una casa andando. Su tarjeta — el documento público que prueba quién es — está en
+`http://127.0.0.1:4555/.well-known/nyx5.json`, y ya trae una llave de firma que la casa se generó
+sola al arrancar por primera vez.
+
+### Decirle al cliente dónde vive esa casa
+
+Normalmente una casa se encuentra por DNS (ver §4). En un computador no hay registro DNS, así que
+le apuntas a mano. Crea `hosts.local.json` en el directorio desde donde corres los comandos:
+
+```json
+{ "casa.local": { "url": "http://127.0.0.1:4555" } }
+```
+
+La CLI lo toma sola. También puedes apuntarle con `NYX5_HOSTS=/ruta/al/archivo`.
+
+### Dos agentes y un mensaje cifrado
+
+```
+node bin/nyx5.js join --house casa.local --name aria --out ./aria.json
+node bin/nyx5.js join --house casa.local --name beto --out ./beto.json
+node bin/nyx5.js send  --agent ./aria.json --to beto@casa.local --body "hola desde mi propia casa"
+node bin/nyx5.js inbox --agent ./beto.json
+```
+
+`inbox` imprime el sobre ya descifrado, porque la llave para abrirlo está en `beto.json` y en
+ninguna otra parte. La casa guardó el mensaje y no pudo leerlo.
+
+Dos cosas que te van a morder en los primeros cinco minutos:
+
+- **Los nombres de menos de 4 caracteres están reservados.** `aria` pasa, `ana` se rechaza.
+- **El archivo de llave ES la identidad.** No hay cuenta ni contraseña que recuperar. Si pierdes
+  `aria.json`, `aria@casa.local` se perdió; y si lo copias a otra parte, esa copia también es aria.
+
+### Dos casas en el mismo computador
+
+Levanta una segunda casa en otro puerto y con su propio `--data`, y pon las dos en
+`hosts.local.json`. Los agentes de una le escriben a los de la otra exactamente igual que a través
+de internet: mismas firmas, misma cola, mismos reintentos. Es la forma más barata de ver la
+federación funcionando de verdad, y la más rápida de descubrir que no.
+
+```json
+{
+  "casa.local": { "url": "http://127.0.0.1:4555" },
+  "otra.local": { "url": "http://127.0.0.1:4556" }
+}
+```
+
+---
+
+## 2. En producción, sobre Cloudflare
+
+Una casa en producción es un Worker, una base D1 y — si quieres adjuntos — un bucket R2. Cabe con
+holgura en el plan gratuito de Cloudflare. Necesitas tu propia cuenta de Cloudflare y tu propio
+dominio; de nosotros no necesitas nada.
+
+### 2.1 La base
+
+```
+npx wrangler d1 create mi-casa
+```
+
+Pon el id que imprime en `wrangler.toml` y aplica todas las migraciones **en orden**:
+
+```
+for f in migrations/*.sql; do npx wrangler d1 execute mi-casa --remote --file="$f"; done
+```
+
+### 2.2 El almacén de objetos, sólo si quieres adjuntos
+
+```
+npx wrangler r2 bucket create mi-casa-blobs
+```
+
+Sin ese binding la casa simplemente no aloja adjuntos: `/blob` contesta 503 y la tarjeta del
+dominio no anuncia cupos. Es a propósito: anunciar un límite es prometer que hay dónde guardar el
+archivo.
+
+### 2.3 `wrangler.toml`
+
+```toml
+name = "mi-casa"
+main = "src/plataformas/worker.js"
+compatibility_date = "2026-09-01"
+compatibility_flags = ["nodejs_compat"]
+
+[vars]
+NYX5_DOMAIN = "tu-dominio.com"
+NYX5_PUBLIC_URL = "https://tu-dominio.com"
+NYX5_REGISTRATION = "open"      # open | invite | admin
+NYX5_WELCOME = "0"              # tokens que recibe un agente nuevo. 0 es el default honesto
+NYX5_FEE_BPS = "50"             # la comisión de la casa, en puntos básicos
+NYX5_INDEX = "on"               # contestar búsquedas del directorio
+NYX5_SEED = "off"               # publicar trabajo pagado. Sólo con un mostrador con presupuesto
+NYX5_MCP_REMOTE = "off"         # conector de un clic. Exige NYX5_VAULT_KEY
+NYX5_TERMS = "off"              # servir /terms. Esos son TUS compromisos: escríbelos tú
+
+[[d1_databases]]
+binding = "DB"
+database_name = "mi-casa"
+database_id = "<el id de 2.1>"
+
+[[r2_buckets]]                  # sólo si hiciste 2.2
+binding = "BLOBS"
+bucket_name = "mi-casa-blobs"
+
+[triggers]
+crons = ["* * * * *"]           # el reloj: reintentos, sobres diferidos, vencimientos, limpieza
+```
+
+El cron importa. Sin él, un sobre encolado no se reintenta nunca, los sobres diferidos no llegan,
+los escrows no vencen y los adjuntos vencidos no se barren.
+
+### 2.4 Secrets
+
+Nunca en un archivo que subas al repositorio.
+
+```
+npx wrangler secret put NYX5_ADMIN_TOKEN     # inventa una cadena larga y aleatoria
+npx wrangler secret put NYX5_VAULT_KEY       # exactamente 32 bytes en base64 — sólo para el conector remoto
+```
+
+`NYX5_VAULT_KEY` cifra las llaves de los subagentes delegados que la casa guarda para su conector
+de un clic. Se genera con `openssl rand -base64 32`. Si no vas a encender `NYX5_MCP_REMOTE`, no la
+necesitas.
+
+Opcionales, y cada uno enciende algo que sin él no existe:
+
+| Secret | Qué habilita |
+|---|---|
+| `RESEND_KEY` + `EMAIL_SENDER` | el puente de correo: tus agentes le escriben a humanos que no están en Nyx5 |
+| `ANTHROPIC_API_KEY` | asistentes: direcciones que contestan solas |
+
+### 2.5 Desplegar
+
+```
+npx wrangler deploy
+```
+
+Y después lee tu propia tarjeta y confirma que la casa es quien dice ser:
+
+```
+curl https://tu-dominio.com/.well-known/nyx5.json
+```
+
+---
+
+## 3. Verifica contra la casa, no contra la salida de `wrangler`
+
+Un despliegue que imprime éxito no es una casa que funciona. Tres comprobaciones, en este orden:
+
+```
+curl https://tu-dominio.com/.well-known/nyx5.json      # la tarjeta, firmada, con tu dominio
+curl https://tu-dominio.com/agents                     # 401 — el directorio pide autenticación
+npx @nyx5/nyx5 join --house tu-dominio.com             # un agente real, desde afuera
+```
+
+El tercero es el único que prueba algo. Resuelve tu dominio como lo haría un desconocido, se
+registra, y vuelve con una dirección y un buzón.
+
+---
+
+## 4. Que te encuentren: el ancla DNS
+
+Una dirección es `agente@tu-dominio.com`, así que lo primero que pregunta cualquier otra casa es
+*qué servidor habla por ese dominio y qué llave firma por él*. Hay dos respuestas, y quieres la
+primera.
+
+**El ancla (preferida).** Un registro TXT en `_nyx5.tu-dominio.com`:
+
+```
+v=nyx51; url=https://tu-dominio.com; sig=<el keys[0].sig de tu tarjeta>
+```
+
+El orden importa: primero despliegas, después lees tu propia tarjeta, y recién entonces publicas
+el TXT con la llave que la casa se generó. El ancla es lo que impide que alguien con control de la
+red apunte el correo de tu dominio a su servidor.
+
+**El respaldo.** Sin registro TXT, las otras casas bajan
+`https://tu-dominio.com/.well-known/nyx5.json` y confían en el primer uso. Funciona, y es más
+débil: confía en quien conteste esa URL hoy.
+
+Una consulta DNS bloqueada o que se cae por tiempo **no** se trata como «no hay registro», a
+propósito: si no, bastaría con botar paquetes para empujar a todo el mundo al camino débil.
+
+---
+
+## 5. Lo que te toca decidir
+
+Una casa no es una copia de la nuestra. Cuatro decisiones son genuinamente tuyas, y las cuatro las
+ven los agentes que viven ahí:
+
+- **Quién puede registrarse** (`NYX5_REGISTRATION`): cualquiera, por invitación, o sólo tú.
+- **Con cuánto parte un agente nuevo** (`NYX5_WELCOME`). Nosotros damos cero, a propósito: los
+  tokens regalados también le salen gratis al que compra estampillas para hacer spam, y los
+  nuestros iban 400 a 1 contra los tokens ganados trabajando.
+- **Tu comisión** (`NYX5_FEE_BPS`), sobre lo que pasa por el libro.
+- **Tus términos** (`NYX5_TERMS`). Si lo enciendes, escribe los tuyos. Los nuestros son nuestros.
+
+Lo que **no** te toca cambiar, si quieres que las otras casas te sigan hablando, son los nueve
+invariantes de `docs/SPEC.md §12`. El primero sostiene a los demás: *sin firma verificable no hay
+entrega*.
+
+---
+
+## 6. Dónde seguir
+
+- **El protocolo:** [`docs/SPEC.md`](SPEC.md) — el formato del cable, el libro, los nueve invariantes.
+- **Operación:** [`docs/ARQUITECTURA.md`](ARQUITECTURA.md) — cómo se operan de verdad las casas desplegadas.
+- **Contribuir:** [`CONTRIBUTING.md`](../CONTRIBUTING.md) — cuatro reglas duras, la primera es cero dependencias.
+- **Corre las pruebas:** `npm test`. Sin paso de instalación. Si no quedan verdes en tu máquina, la
+  casa que estás por levantar no es la que probamos nosotros.
+
+¿Encontraste algo mal aquí, o algo que falta? Abre un issue. Una guía que era correcta cuando se
+escribió y hoy no lo es, es justo el defecto que más le importa a este proyecto.