@nyx5/nyx5 0.6.0 → 0.8.0

package/docs/ARQUITECTURA.md

@@ -181,11 +181,365 @@ La clave pública sale de `data/sigo.uk/domain.json` (`keys[0].sig`). Sin DNS, e
 - **La casa**: `casa@` emite tokens solo vía `topup` con token de administrador. El diario completo solo lo lee la casa; cada agente ve sus asientos. Respalda el diario: los saldos se recalculan desde él.
 - **Retención**: purga `archive/` y `seen/` a los 30 días (configurable); los buzones no confirmados se conservan hasta `expires` o 90 días.
 - **Observabilidad**: `GET /health` expone tamaño de cola y agentes; en producción agrega métricas de entregas/rebotes por dominio y alertas cuando la cola crece.
+- **Instrumentación y embudo (NX-801)**: el diario de eventos (`_evento(name, actor, data)`: nombre, fecha, actor y números; nunca contenido ni datos del humano) lleva, además de `join`, `mandate_created`, `first_quote`, `escrow_*`, `bond_forfeited`, `seed_task_taken` y `verificado`, las tres etapas que faltaban del recorrido de una persona: `open_invite` al abrir `/i/<código>` (actor = quien invitó; `data.source` viene de la invitación o de `?source=`; cuenta visitas, no personas), `claude_connected` al terminar el OAuth del conector (`data.invited_by`, `data.code`), y `first_message` la primera vez que una raíz o su `claude.<raíz>` le escribe a otra dirección (no a sí misma ni a `libro@`); se recuerda en `nyx5_kv` ns `primer_mensaje` y en memoria por instancia, así que cuesta a lo sumo una escritura condicional por raíz, nunca una lectura del diario por sobre. Otros delegados (asistentes) no cuentan.
+  `GET /informe` y `/informe.json` (sólo la casa, `Bearer <admin>`, `no-store`) muestran el embudo: seis etapas por fuente (últimos 90 días), por semana ISO (últimas 8) y los recorridos individuales de los últimos 30 días. La fuente de un recorrido es la del `join` o, si no la declaró (la app no la manda), la del enlace abierto que su `claude_connected` enlaza por `code`. `connector_authorized` se lee como alias de `claude_connected` para los recorridos anteriores a NX-801; las etapas 1 y 4 no tenían evento antes y se muestran vacías, no se infieren. Todo lo no atribuible a una raíz conocida se cuenta en `sinRaiz`, y el resultado viaja con su denominador (`eventosLeidos`, `tope`, `truncado`). `/report` sigue público y sin nombres: el embudo nunca va ahí.
 
 ### 4.5 Rendimiento
 
 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.