bug_bunny 4.19.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c751d42f963af2dc145005dba7b6245b0dc9fa549cacecb824e6a5cc2c3232d
-  data.tar.gz: c7c602f3f96a47a85080b287fd87435bb161abcab6b5358f51b45ed05fd1428a
+  metadata.gz: e1076566b6a3b8c25f6f00fc624c92681e8db881ffc3b8d6640da3bb7158333b
+  data.tar.gz: 2510fe871ec6f32804dba3faa7f1110408656e8cff30d2c0d537c7d0b30e1686
 SHA512:
-  metadata.gz: e8e1e583486fec890b5ccdedb77f99f1954f37e9a4217afe1aee0085ca8483f242a966643bcce5da5a7a180d0223850039a883ae9ce92b8be91a02c7beaac7b7
-  data.tar.gz: 71305eaf4dec9b4bf3fae7bf19bbb3fd997d75c409c6d5239d52030c1c7b5833f48f675f5bbcf187ef16334c0286f7a780675add36980c5b927ca592c68ab9d7
+  metadata.gz: 13525491f89b99f1e1be12663f64990109e17b9da22e034ecea463a3fda5ff68abfb3ab10fdf274d43df5460b3c74eabd14e1699e2af7f8c38e608a78e22cb69
+  data.tar.gz: 9f31c6ed9fbfff650e2770f970ab94e49979f8eec8b254c212817ca410106b4f4293cc9b6cde87f382145a2483f639aabe0998134c5656b7ec6b053aebcb7c73

data/AGENTS.md

@@ -0,0 +1,43 @@
+# AGENTS.md — bug_bunny
+
+Entrada de harness para agentes que trabajan en este repo. Para el contrato de
+proyecto y convenciones de equipo, ver `CLAUDE.md`. Para la entrada humana, ver
+`README.md`; para la entrada agente version-locked, `skill/SKILL.md`.
+
+## Mapa de conocimiento
+
+> Stanza RFC-008 r2 — **indexa, no duplica**. Cada fila apunta al artefacto de
+> detalle que es la fuente de verdad de esa capa. Leé el artefacto antes de
+> responder sobre su capa.
+
+| capa | artefacto | estado | qué responde |
+|---|---|---|---|
+| Comportamiento | `docs/behavior/behavior.md` | completo (6 flujos) | secuencias de publish/RPC/consume/confirms, contrato de error-wrapping |
+| Glosario | `docs/glossary/glossary.md` | parcial (acreta por PR) | término de negocio → binding físico en `lib/` |
+| Errores | `docs/errors/errors.md` | completo (§a/b/d estructura + §c política inferida) | jerarquía de excepciones públicas, mapeo `status→excepción`, shape del payload, política retry |
+| Configuración | `docs/config/configuracion.md` | completo (estructura + enrich §f/g/h) | opciones de `Configuration`, defaults, failure-mode/threading, inyecciones del `Railtie`, ENV sugeridas |
+| Dependencias consumidas | `docs/consumed/rabbitmq.md` | completo (estructura + enrich §c/e) | qué consume del broker RabbitMQ vía `bunny`, mapeo error-Bunny→excepción, retry/degradación |
+| Test | `docs/test/test.md` | completo (estructura + enrich §e-h) | suites RSpec/Minitest, CI, contract-assessment, link a incidentes (#49/#52) |
+| Release | `docs/release/release.md` | completo | patrón gema-tag, versionado, publish a RubyGems |
+| Datos | — | n/a | gema sin DB |
+| Operaciones / Interfaz / Topología | — | dev-structure F2 no implementado | contrato embebido en `README.md`/`skill/SKILL.md` (interim RFC-008 §2) |
+| Eventos (RFC-005) | — | n/a | la gema es el transporte de eventos, no declara un catálogo de eventos de dominio propio |
+| Seguridad (RFC-017) | — | n/a | sin authn/authz propias; el único control es el guard anti-RCE (clase enrutada debe heredar de `BugBunny::Controller`, si no → 403), cubierto en `docs/errors/` |
+| Multi-tenancy (RFC-023) | — | n/a | sin modelo de tenant propio; el aislamiento es por `vhost` de RabbitMQ (config) |
+| Data-lifecycle (RFC-026) | — | n/a | gema sin DB ni datos persistidos propios |
+
+## Enriquecimiento
+
+Completo en errors (§c), config (§f/g/h), consumed (§c/e) y test (§e-h), anclado
+a YARD/specs/CHANGELOG. Pendiente de **verificación humana** (inferencias):
+
+- `docs/errors/errors.md` §c — política retry inferida de HTTP/AMQP (`confidence:medium`); confirmar idempotencia de re-publish y caso `RemoteError` con consumidores reales.
+- `docs/glossary/glossary.md` — parcial por diseño, acreta por PR.
+
+## Convenciones operativas
+
+- Ruby: `.ruby-version` · gemas: `Gemfile.lock` · manager: chruby + Bundler.
+- Antes de commitear: `bundle exec rubocop -a` (base `rubocop-rails-omakase`),
+  `bundle exec rspec`, YARD incremental (`bundle exec yard stats --list-undoc`).
+- Releases: `/gem-release` (el GitHub Action publica a RubyGems al pushear tag `v*`).
+- Doc por-PR: si tocás una capa, mové su artefacto en el mismo PR (régimen RFC-001).

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [5.0.0] - 2026-07-01
+
+> **BREAKING.** Se elimina la constante pública `BugBunny::SecurityError`. Aunque la excepción nunca se *levantaba*, su **ausencia rompe en evaluación**: un `rescue BugBunny::SecurityError` en un consumidor resuelve la constante cuando *cualquier* excepción entra a ese bloque → `NameError` que enmascara la excepción original. Por eso es breaking real, no inerte.
+
+### Removed
+- **`BugBunny::SecurityError` eliminada:** introducida en `4f27bea` ("security controller") como la excepción prevista del control anti-RCE, pero **nunca se cableó** — ninguna ruta de código la levanta. La protección real (la clase enrutada debe heredar de `BugBunny::Controller`) vive en `Consumer` (`consumer.rb:222-228`) y responde **403 Forbidden** + reject + log `consumer.security_violation`, no una excepción. Eliminar la clase **no debilita** la protección (el guard 403 queda intacto). Doc ajustada (`docs/errors/`, README, skill). — @Gabriel
+
+  **Migración para consumidores:** quitar cualquier `rescue BugBunny::SecurityError`; el caso de controlador inválido llega como respuesta **403** en el envelope RPC (mapeable a `BugBunny::ClientError`/manejo de status), no como excepción local.
+
+  **Alcance verificado:** el grep que confirmó "nunca levantada" fue **in-repo** (lib + spec + test de esta gema). No se auditaron apps/gemas consumidoras externas — el bump MAJOR es la salvaguarda para ellas.
+
+### Correcciones
+- **CI: el workflow disparaba en `push` a `master`, pero la rama por default es `main` (#56):** el job de tests (Ruby 3.4.4) nunca corría en push a `main`, solo entraba por `pull_request`. Apuntado a `main`. — @Gabriel
+
+### Documentación
+- **Cobertura de arquitectura completa (dev-* / RFC-artefacto):** nuevas capas `docs/errors/` (RFC-020), `docs/config/` (RFC-012), `docs/consumed/` (RFC-018) y `docs/test/` (RFC-013), con enriquecimiento semántico (política de errores, retry/degradación, threading, contract-assessment); `docs/release/` re-anclado a RFC-014 `accepted`; `AGENTS.md` con stanza "Mapa de conocimiento". Empaquetado version-locked en la gema (#54, #55, #57). — @Gabriel
+
 ## [4.19.0] - 2026-06-25
 
 > Capa de errores transport-agnostic (#52). Cambio **aditivo y retrocompatible**: `.message` no se degrada y se suman dos accesores. Bump minor.

data/CLAUDE.md

@@ -13,10 +13,20 @@ BugBunny es una gema Ruby que implementa una capa de enrutamiento RESTful sobre
   `skill/SKILL.md` agente version-locked) **indexan, no duplican**.
   Artefactos generados por `dev-structure` / `dev-enrich`; compuestos por
   `dev-compose`. Verificación humana antes de commitear.
-- **Estado actual:** `docs/data` = n/a (gema sin DB, declarado solo en índice);
-  `docs/glossary` parcial (acreta por PR); `docs/behavior` completo (6 flujos,
-  backfill on-demand); operaciones/interfaz/topología = dev-structure F2 no
-  implementado.
+- **Estado actual:**
+  - `docs/data` = n/a (gema sin DB, declarado solo en índice).
+  - `docs/behavior` completo (6 flujos, backfill on-demand).
+  - `docs/glossary` parcial (acreta por PR).
+  - `docs/errors` (RFC-020) completo: §a/§b/§d (estructura) + §c política
+    (enrich, **inferida** de HTTP/AMQP, verificación humana pendiente).
+  - `docs/config` (RFC-012) completo: inventario §a-§e/§i + enrich §f/§g/§h
+    (failure-mode/threading, anclado a YARD); §j n/a.
+  - `docs/consumed` (RFC-018) RabbitMQ-vía-`bunny` completo: §a/§b/§d + enrich
+    §c/§e (retry/backoff/degradación, anclado a `consumer.rb`).
+  - `docs/test` (RFC-013) completo: estructura §a-§d + enrich §e-§h
+    (contract-assessment, link a incidentes #49/#52, gaps de CI).
+  - operaciones/interfaz/topología (RFC-003/004/006) = dev-structure F2 no
+    implementado (interim RFC-008 §2).
 - **Para agentes AI**: `skill/SKILL.md` (empaquetada en el `.gem`) +
   `skill/references/`.
 - **Coexistencia transitoria con destino pendiente (RFC-008 §2 — interim de

data/README.md

@@ -379,7 +379,6 @@ BugBunny maps RabbitMQ responses to a semantic exception hierarchy, similar to h
 BugBunny::Error
 ├── CommunicationError                  (wraps any Bunny::Exception — TCP/auth/channel — at the gem boundary; .cause preserves the original)
 ├── ConfigurationError                  (invalid config attribute)
-├── SecurityError                       (unauthorized controller resolution)
 ├── PublishNacked                       (broker basic.nack on :confirmed publish)
 ├── PublishUnroutable                   (broker basic.return on mandatory + :confirmed)
 ├── ClientError (4xx)

data/docs/config/configuracion.md

@@ -0,0 +1,172 @@
+# Configuración — bug_bunny
+
+> meta: artefacto configuración · RFC-012 · generado `arch-structure` (inventario
+> §a-§e/§i) + `arch-enrich` (§f/§g/§h/§j) · anclado a `24ea397`,
+> `lib/bug_bunny/configuration.rb`, `lib/bug_bunny.rb`, `lib/bug_bunny/railtie.rb`,
+> `lib/bug_bunny/consumer.rb`,
+> `lib/generators/bug_bunny/install/templates/initializer.rb` · fecha 2026-06-30
+> · cobertura: §a-§e/§i (estructura) + §f/§g/§h (enrich, anclado a YARD) completas;
+> §j n/a.
+
+## 1. Resumen
+
+Gema configurable vía `BugBunny.configure { |c| ... }` (`bug_bunny.rb:59`) sobre
+la clase `Configuration` (`configuration.rb`): atributos con **code-defaults**
+seguros, validados por `validate!` al cierre del bloque. La gema **no lee `ENV[`
+en `lib/`**; el `ENV.fetch` vive en el **template** que sugiere al consumidor
+(`initializer.rb`). Inyecta al host vía `Railtie`.
+
+## 2. Cuerpo
+
+### a. Hecho verificable
+
+- **Total opciones (`Configuration`):** 29 (attr_accessor/reader).
+- **Validadas requeridas (`VALIDATIONS`, `configuration.rb:25-37`):** 5 (`host`,
+  `port`, `username`, `password`, `vhost` — `required: true`; igual tienen
+  default, `validate!` exige no-vacío).
+- **Con default:** 29 (todas; defaults en `initialize`/`init_callback_defaults`).
+- **Con rango validado:** 7 (`port`, `heartbeat`, `connection_timeout`,
+  `read_timeout`, `write_timeout`, `rpc_timeout`, `channel_prefetch`).
+- **Secretas (por nombre):** 1 (`password`).
+- **ENV leídas por la gema en `lib/`:** 0 (config 100% por code-default + bloque).
+
+### b. Inventario base
+
+Origen `code-default` salvo nota. Consumidor = `configuration.rb` (default en
+`initialize`) salvo indicado.
+
+| nombre | tipo | requerida | default | origen | consumidor | secret? |
+|---|---|---|---|---|---|---|
+| `host` | String | sí (validate!) | `'127.0.0.1'` | code-default | `configuration.rb:182` | no |
+| `port` | Integer | sí (validate!, 1..65535) | `5672` | code-default | `:183` | no |
+| `username` | String | sí (validate!) | `'guest'` | code-default | `:184` | no |
+| `password` | String | sí (validate!) | `'guest'` | code-default | `:185` | **sí** |
+| `vhost` | String | sí (validate!) | `'/'` | code-default | `:186` | no |
+| `logger` | Logger | no | `Logger.new($stdout)` INFO | code-default | `:188` | no |
+| `bunny_logger` | Logger | no | `Logger.new($stdout)` WARN | code-default | `:191` | no |
+| `automatically_recover` | Boolean | no | `true` | code-default | `:193` | no |
+| `network_recovery_interval` | Integer | no | `5` | code-default | `:194` | no |
+| `max_reconnect_attempts` | Integer/nil | no | `nil` (reintenta ∞) | code-default | `:195` | no |
+| `max_reconnect_interval` | Integer | no | `60` | code-default | `:196` | no |
+| `connection_timeout` | Integer | no (1..300) | `10` | code-default | `:197` | no |
+| `read_timeout` | Integer | no (1..300) | `30` | code-default | `:198` | no |
+| `write_timeout` | Integer | no (1..300) | `30` | code-default | `:199` | no |
+| `heartbeat` | Integer | no (0..3600) | `15` | code-default | `:200` | no |
+| `continuation_timeout` | Integer (ms) | no | `15000` | code-default | `:201` | no |
+| `channel_prefetch` | Integer | no (1..10000) | `1` | code-default | `:202` | no |
+| `rpc_timeout` | Integer | no (1..3600) | `10` | code-default | `:203` | no |
+| `health_check_interval` | Integer | no | `60` | code-default | `:204` | no |
+| `health_check_file` | String/nil | no | `nil` (desactivado) | code-default | `:207` | no |
+| `controller_namespace` | String | no | `'BugBunny::Controllers'` | code-default | `:210` | no |
+| `log_tags` | Array | no | `[:uuid]` | code-default | `:212` | no |
+| `exchange_options` | Hash | no | `{}` | code-default | `:215` | no |
+| `queue_options` | Hash | no | `{}` | code-default | `:216` | no |
+| `consumer_middlewares` | Stack (attr_reader) | no | `Stack.new` | code-default | `:218` | no |
+| `rpc_reply_headers` | Proc/nil | no | `nil` | code-default | `:251` | no |
+| `on_rpc_reply` | Proc/nil | no | `nil` | code-default | `:252` | no |
+| `on_return` | Proc/nil | no | `nil` | code-default | `:253` | no |
+| `nack_raise` | Boolean | no | `true` | code-default | `:254` | no |
+| `return_raise` | Boolean | no | `true` | code-default | `:255` | no |
+
+> **Override por request:** `nack_raise` y `return_raise` se sobreescriben por
+> llamada con `nack_raise:` / `return_raise:` en `Client#publish` (scope-override
+> → detalle a `arch-enrich`).
+
+### c. Meta-templates
+
+El install template (`initializer.rb`) **sugiere al consumidor** wirear 4 ENV
+(la gema no las lee — el consumidor las pasa al bloque `configure`):
+
+| plantilla | template | instancias |
+|---|---|---|
+| `RABBITMQ_{X}` → `config.{y}` | `ENV.fetch('RABBITMQ_{X}', '{default}')` | `RABBITMQ_HOST`→host (`'localhost'`), `RABBITMQ_USERNAME`→username (`'guest'`), `RABBITMQ_PASSWORD`→password (`'guest'`), `RABBITMQ_VHOST`→vhost (`'/'`) |
+
+> `spec/spec_helper.rb` usa `RABBITMQ_HOST` / `RABBITMQ_USER` / `RABBITMQ_PASS`
+> (nombres distintos al template) — convención de test, no contrato.
+
+### d. Derivaciones simples
+
+- `url` ← `"amqp://#{username}:#{password}@#{host}:#{port}/#{vhost}"`
+  (`configuration.rb:225`).
+- `create_connection(**options)` ← `merge_connection_options(options)` sobre la
+  config global; las options explícitas pisan los defaults (`bug_bunny.rb:88`).
+
+### e. Scheduling
+
+**n/a** — la gema no trae `sidekiq.yml`/`queue.yml`/`recurring.yml` ni cron.
+`health_check_interval` es polling interno de salud, no un scheduler.
+
+### i. Inyecciones al host (`Railtie`, `railtie.rb`)
+
+| inyección | qué hace | ancla |
+|---|---|---|
+| `initializer 'bug_bunny.add_autoload_paths'` | registra `app/rabbit` en el autoloader (Zeitwerk, `eager_load: true`) si existe | `:15-18` |
+| `config.after_initialize` → `ForkTracker.after_fork` | cierra la conexión heredada en cada fork (Rails 7.1+) | `:24-26` |
+| `config.after_initialize` → `Puma.events.on_worker_boot` | mismo cierre, hook legacy Puma <5 | `:30-34` |
+| `rake_tasks` | carga `tasks/bug_bunny.rake` (`bug_bunny:sync`) | `:38-40` |
+| `Spring.after_fork` | cierra conexión en preloader Spring | `:43-47` |
+
+### f. Enriquecimiento semántico
+
+Agrupado por familia. Anclado a los YARD de `configuration.rb` y al comportamiento
+del código.
+
+| familia | categoría | failure-mode | side-effect | business-reason |
+|---|---|---|---|---|
+| Conexión (`host`/`port`/`username`/`password`/`vhost`) | conectividad | valor inválido/vacío → `ConfigurationError` en `validate!`; credencial/host errados → `CommunicationError` al conectar (`bug_bunny.rb:95`) | abre socket TCP al broker | identidad y destino del broker; `vhost` aísla ambientes |
+| Timeouts (`connection_timeout`/`read_timeout`/`write_timeout`/`heartbeat`/`continuation_timeout`) | resiliencia/latencia | muy bajo → cortes espurios bajo carga; muy alto → detección de fallo lenta | — | tuning de la conexión Bunny; `heartbeat` detecta conexiones zombi |
+| `rpc_timeout` | latencia | el worker remoto no responde a tiempo → `RequestTimeout` (`producer.rb:124,214`) | bloquea el hilo llamante hasta el timeout | techo de espera de un RPC síncrono |
+| Resiliencia (`automatically_recover`/`network_recovery_interval`/`max_reconnect_attempts`/`max_reconnect_interval`) | resiliencia | `max_reconnect_attempts` agotado → el Consumer re-levanta y muere (`consumer.rb:110-112`) | reintentos con **backoff exponencial** `network_recovery_interval * 2^(n-1)` cap `max_reconnect_interval` (`consumer.rb:115-118`) | sobrevivir caídas transitorias del broker sin perder el worker |
+| QoS (`channel_prefetch`) | rendimiento | alto → un worker lento acapara mensajes; `1` → menor throughput | controla unacked in-flight (backpressure) | balancea fairness vs throughput (default `1` = fair round-robin) |
+| Health (`health_check_interval`/`health_check_file`) | observabilidad | `health_check_file` no escribible → el touch falla (degradación de visibilidad, no del flujo) | **escribe (touch) un archivo** en cada health check OK; `nil` desactiva | probe para orquestadores (K8s/Swarm) |
+| Callbacks (`on_return`/`on_rpc_reply`/`rpc_reply_headers`) | extensibilidad | una excepción en `on_return` se captura pero **degrada visibilidad** (YARD `configuration.rb:147`) | corren en hilos sensibles (ver §h) | propagar trace-context / alertar unroutable |
+| Confirms (`nack_raise`/`return_raise`) | integridad de entrega | `false` → NACK/return solo se logea, la llamada retorna `202` (modo legacy, posible pérdida silenciosa) | habilitan el raise de `PublishNacked`/`PublishUnroutable` | elegir entre fail-fast vs best-effort en publish confirmado |
+| Routing (`controller_namespace`) | seguridad | clase resuelta no subclase de `BugBunny::Controller` → el worker responde **403** + reject (guard anti-RCE, `consumer.rb:222-228`) | acota qué clases son enrutables | superficie de control de RCE |
+| Logging (`logger`/`bunny_logger`/`log_tags`) | observabilidad | — | salida a `$stdout` por default | trazabilidad estructurada |
+| Infra (`exchange_options`/`queue_options`) | infraestructura | options incompatibles con el broker → `PreconditionFailed` (vía `CommunicationError`) | defaults globales mergeados por recurso | declaración AMQP por default |
+
+### g. Ramificadores intra-config
+
+- `health_check_file = nil` (default) **desactiva** el touchfile aunque
+  `health_check_interval` siga corriendo (`configuration.rb:99-101,207`).
+- `return_raise` es **inerte cuando `mandatory: false`** — sin `mandatory` el
+  broker nunca retorna, así que el flag no tiene efecto (`configuration.rb:171`).
+- `nack_raise`/`return_raise` se sobreescriben **por request** (`Client#publish`),
+  ganando sobre el valor global (scope-override).
+
+### h. Threading
+
+| opción | hilo de ejecución | restricción |
+|---|---|---|
+| `on_return` | **hilo interno del consumidor de Bunny** (`configuration.rb:147`) | debe ser rápido y no lanzar; BugBunny captura, pero degrada visibilidad |
+| `on_rpc_reply` | **hilo llamante** tras recibir el reply RPC (`configuration.rb:132`) | hidrata trace-context en el publisher |
+| `rpc_reply_headers` | hilo del consumer, justo antes del `basic_publish` del reply (`configuration.rb:125`) | debe retornar un Hash de headers |
+| reconexión del Consumer | hilo del `subscribe` loop (`consumer.rb:90,122`) | `sleep wait` bloquea ese hilo durante el backoff |
+
+### j. Inyección a gemas configuradas
+
+**n/a** — la gema **no** configura otras gemas vía bloque `Gema.configure` en
+initializers; expone su propio `BugBunny.configure`. El `Railtie` inyecta al
+host (§i), no a gemas terceras.
+
+## 3. Inferencias
+
+- **`requerida` de host/port/username/password/vhost:** `VALIDATIONS` las marca
+  `required: true`, pero `initialize` les da default → nunca son `nil` salvo que
+  el consumidor las setee a `''`/`nil`. Marcadas `sí (validate!)`: el contrato es
+  "no-vacías al cierre del bloque", no "sin default". `confidence: high`.
+- **`password` secret?=sí** por nombre (regla RFC-012). El default `'guest'` es
+  el usuario default de RabbitMQ (placeholder), **no** un secreto real → ver §4.
+
+## 4. Cobertura y fronteras
+
+- §a-§e/§i (estructura) + §f/§g/§h (enrich) **completas** al commit ancla; §j n/a.
+- **Linter de secretos (advisory):** `password` default `'guest'` y el template
+  `RABBITMQ_PASSWORD` default `'guest'` matchean el patrón de secreto, pero el
+  valor es el placeholder default de RabbitMQ, **no** un secreto hardcodeado. El
+  consumidor debe inyectar la credencial real vía ENV en prod (lo dice el header
+  del template). No es hallazgo de fuga.
+- **Enriquecimiento (§f/§g/§h):** anclado a los YARD de `configuration.rb` y al
+  backoff real de `consumer.rb` — no inventado. La elección de valores concretos
+  (tuning de timeouts/prefetch por ambiente) es decisión operativa del consumidor,
+  no del artefacto.

data/docs/consumed/rabbitmq.md

@@ -0,0 +1,102 @@
+# Dependencia consumida: RabbitMQ (vía `bunny`) — bug_bunny
+
+> meta: artefacto consumed · RFC-018 · generado `arch-structure` (§a/§b/§d) +
+> `arch-enrich` (§c/§e) · anclado a `24ea397`, `bug_bunny.gemspec`,
+> `lib/bug_bunny.rb`, `lib/bug_bunny/session.rb`, `lib/bug_bunny/producer.rb`,
+> `lib/bug_bunny/consumer.rb`, `lib/bug_bunny/middleware/raise_error.rb` · fecha
+> 2026-06-30 · cobertura: §a/§b/§d (estructura) + §c/§e (enrich, anclado a
+> `consumer.rb`) completas.
+
+## 1. Resumen
+
+La gema consume **un único sistema externo: el broker RabbitMQ**, vía el SDK
+`bunny ~> 2.24` (AMQP 0-9-1). Es el corazón del gem: toda publicación, consumo,
+RPC y declaración de infraestructura pasa por `Bunny`. El pooling de conexiones
+lo da `connection_pool` (infra, ver §4).
+
+## 2. Cuerpo
+
+### a. Identidad
+
+| campo | valor |
+|---|---|
+| proveedor / sistema | **RabbitMQ broker** |
+| sub-tipo | **externo** (sistema de mensajería, no un repo del fleet) |
+| transporte | AMQP 0-9-1 (TCP) |
+| cliente nuestro | gem `bunny ~> 2.24` (`bug_bunny.gemspec:36`), envuelto por `BugBunny.create_connection` (`bug_bunny.rb:87`) + `Session` |
+| auth | SASL user/pass (`username`/`password` de `Configuration`); URL `amqp://user:pass@host:port/vhost` |
+| ancla (doc proveedor) | Bunny: https://github.com/ruby-amqp/bunny · AMQP 0-9-1: https://www.rabbitmq.com/amqp-0-9-1-reference.html |
+
+### b. Operaciones consumidas (subset usado)
+
+| operación Bunny | dónde | qué mandamos / esperamos |
+|---|---|---|
+| `Bunny.new(opts).start` | `bug_bunny.rb:89,93` | abre `Bunny::Session` (conexión TCP + handshake); espera sesión iniciada |
+| `after_recovery_completed` | `bug_bunny.rb:90` | callback de recuperación de conexión → log `bug_bunny.connection_recovered` |
+| `session.create_channel` | `session.rb:177` (rescata fallo) | abre canal AMQP |
+| reconnect / recovery | `session.rb:285` | reconexión; en fallo → `CommunicationError` |
+| publish confirmado | `producer.rb:90` (`Producer#confirmed`) | `basic.publish` + publisher confirms; espera ACK/NACK |
+| publisher confirms (`nacked_set`) | `producer.rb:235` | lee NACKs del canal → `PublishNacked` |
+| `mandatory: true` + `basic.return` | `producer.rb:325` | mensaje no ruteable → `PublishUnroutable` (reply_code 312 NO_ROUTE) |
+| RPC (publish + reply-to consume) | `producer.rb:124,214` | request/response; timeout → `RequestTimeout` |
+| AMQP publish/consume genérico | `client.rb:168` | cualquier `Bunny::Exception` en la frontera → `CommunicationError` |
+
+> El mapa completo de operaciones que la gema **expone** (no las que consume)
+> es la capa operaciones (RFC-003, `docs/api/`, pendiente F2).
+
+### d. Errores del proveedor → excepción nuestra
+
+`bunny` levanta `Bunny::Exception` (y subclases). La gema las **envuelve** en la
+frontera de abstracción. La columna "excepción nuestra" **referencia** el
+catálogo `docs/errors/errors.md` (RFC-020), no lo redefine.
+
+| error del proveedor (Bunny) | excepción nuestra | dónde se mapea |
+|---|---|---|
+| `Bunny::Exception` (TCP fail, auth fail, vhost inválido) al conectar | `CommunicationError` | `bug_bunny.rb:95-98` |
+| `Bunny::Exception` al crear canal | `CommunicationError` | `session.rb:177` |
+| `Bunny::Exception` en reconexión | `CommunicationError` | `session.rb:285` |
+| `Bunny::Exception` en publish confirmado | `CommunicationError` | `producer.rb:90` |
+| `Bunny::Exception` / `ConnectionClosedError` en publish/consume | `CommunicationError` | `client.rb:168` |
+| NACK del broker (publisher confirms) | `PublishNacked` | `producer.rb:235` |
+| `basic.return` (mandatory, no ruteable) | `PublishUnroutable` | `producer.rb:325` |
+| timeout esperando reply RPC | `RequestTimeout` | `producer.rb:124,214` |
+
+> Regla: los callers no rescatan `Bunny::*` directo — `rescue
+> BugBunny::CommunicationError` cubre cualquier fallo de transporte/broker. La
+> original queda en `.cause`.
+
+### c. Retry / idempotencia
+
+| aspecto | comportamiento (anclado) |
+|---|---|
+| recuperación de conexión | `automatically_recover = true` (default): Bunny recupera canales/suscripciones tras corte TCP (`configuration.rb:60-61`). |
+| retry del Consumer | `Consumer#subscribe` reintenta en cualquier `StandardError` con **backoff exponencial** `network_recovery_interval * 2^(n-1)` cap `max_reconnect_interval`, hasta `max_reconnect_attempts` (`nil` = ∞) (`consumer.rb:106-124`). |
+| ack | `manual_ack: true` (`consumer.rb:90`) → entrega **at-least-once**: si el worker cae tras procesar pero antes del ack, el mensaje se re-entrega. **El handler debe ser idempotente.** |
+| retry de publish | **no automático** — un publish fallido levanta `CommunicationError`/`PublishNacked`; reintentarlo puede **duplicar** salvo dedup aguas abajo. |
+| RPC | `request` espera reply hasta `rpc_timeout`; el retry de un RPC mutante requiere idempotencia (correlación por `correlation_id`). |
+
+### e. Degradación (si RabbitMQ cae)
+
+- **Al conectar:** `create_connection` levanta `CommunicationError` (`bug_bunny.rb:95`); no hay fallback ni cola local — el caller decide (circuit-break/alertar).
+- **Consumer:** entra al loop de reconexión con backoff; por default (`max_reconnect_attempts = nil`) **reintenta indefinidamente**, logueando `consumer.connection_error` con `retry_in_s` (`consumer.rb:120-122`). Si se fija un máximo y se agota → `consumer.reconnect_exhausted` y re-raise (el worker muere).
+- **Publisher:** cada publish/RPC sobre conexión caída levanta `CommunicationError` (envuelto en `client.rb:168`); **sin buffering** — el mensaje no sale.
+- **Sin circuit-breaker propio:** la gema no trae breaker ni outbox; la resiliencia aguas arriba (reintentar el comando, encolar, alertar) es responsabilidad del consumidor.
+
+## 3. Inferencias
+
+- El gem declara **dependencia directa** solo de RabbitMQ-vía-bunny. Las demás
+  gemas del gemspec (`activemodel`, `activesupport`, `rack`, `json`,
+  `concurrent-ruby`, `ostruct`) son librerías de soporte, no sistemas externos
+  consumidos → van a topología (RFC-006), no acá.
+
+## 4. Cobertura y fronteras
+
+- §a/§b/§d (estructura) + §c/§e (enrich, anclado a `consumer.rb`) **completas**.
+- **`connection_pool` (`>= 2.4`):** utilidad de pooling de las conexiones Bunny
+  (`Resource.connection_pool`), **no** un sistema externo con su propio
+  contrato de error de red → no es entrada consumed; el timeout de pool
+  (`ConnectionPool::TimedStack`) nace dentro de `@pool.with` y termina envuelto
+  como `CommunicationError` (ver `CHANGELOG` #49). Pertenece a topología.
+- **Subset, no la API completa de Bunny:** solo se documentan las operaciones
+  que el gem invoca. Parámetros de tuning (heartbeat, prefetch, timeouts) viven
+  en `docs/config/`.

data/docs/errors/errors.md

@@ -0,0 +1,196 @@
+# Errores — bug_bunny
+
+> meta: artefacto errores · RFC-020 · generado `arch-structure` (§a/§b/§d) +
+> `arch-enrich` (§c) · anclado a `d0533bf`, `lib/bug_bunny/exception.rb`,
+> `remote_error.rb`, `middleware/raise_error.rb`, `controller.rb`, `consumer.rb`
+> · fecha 2026-06-30 · cobertura: §a/§b/§d completas (estructura); §c política
+> completa (enrich, **inferida** de HTTP/AMQP — verificación humana pendiente).
+
+## 1. Resumen
+
+Catálogo del unhappy path que la gema **emite** a sus consumidores: jerarquía de
+excepciones bajo `BugBunny::Error`, el mapeo `status RPC → excepción` que aplica
+`Middleware::RaiseError` en el lado cliente, y el shape del envelope de error que
+emite el lado worker (`Controller`). La gema es **agnóstica al payload**: expone
+la materia prima (`status` + `raw_response`) y no interpreta la estructura de
+dominio del cuerpo (#52).
+
+## 2. Cuerpo
+
+### a. Inventario de excepciones públicas
+
+Jerarquía (todas bajo `BugBunny::Error < ::StandardError`):
+
+```
+::StandardError
+└── BugBunny::Error                      base · attr_accessor :status, :raw_response (#52)
+    ├── CommunicationError               fallo de red/conexión/protocolo AMQP
+    ├── ConfigurationError               configuración inválida de la gema
+    ├── PublishNacked                    broker NACK en publish :confirmed
+    ├── PublishUnroutable                broker return (mandatory) sin binding
+    ├── ClientError                      base 4xx
+    │   ├── BadRequest                   400
+    │   ├── NotFound                     404
+    │   │   └── RoutingError             404 · ruta RPC inexistente en el remoto
+    │   ├── NotAcceptable                406
+    │   ├── RequestTimeout               408 · y timeout local de RPC
+    │   ├── Conflict                     409
+    │   └── UnprocessableEntity          422 · parsea body, expone error_messages
+    └── ServerError                      base 5xx
+        ├── InternalServerError          500 genérico
+        └── RemoteError                  500 · propaga excepción serializada del worker
+```
+
+| excepción | jerarquía base | qué la levanta (ancla) |
+|---|---|---|
+| `Error` | `::StandardError` | base — no se levanta directa salvo `resource.rb:122` (pool ausente) |
+| `CommunicationError` | `Error` | `bug_bunny.rb:96`, `session.rb:177,285`, `producer.rb:90`, `client.rb:168` — envuelve cualquier `Bunny::Exception` en la frontera del gem; original en `.cause` |
+| `ConfigurationError` | `Error` | `configuration.rb:262,269,277` — validación al final de `BugBunny.configure` |
+| `PublishNacked` | `Error` | `producer.rb:235` — NACK del broker en modo `:confirmed`. Attrs: `path`, `nacked_count`. Opt-out `nack_raise: false` |
+| `PublishUnroutable` | `Error` | `producer.rb:325` — `basic.return` con `mandatory: true`. Attrs: `path`, `exchange`, `routing_key`, `reply_code`, `reply_text`, `correlation_id`. Opt-out `return_raise: false` |
+| `ClientError` | `Error` | `raise_error.rb:170` — 4xx no mapeado explícito |
+| `BadRequest` | `ClientError` | `raise_error.rb:38` — status 400 |
+| `NotFound` | `ClientError` | `raise_error.rb:155` — status 404 genérico |
+| `RoutingError` | `NotFound` | `raise_error.rb:152` — status 404 con `body['error_type'] == 'routing_error'` |
+| `NotAcceptable` | `ClientError` | `raise_error.rb:40` — status 406 |
+| `RequestTimeout` | `ClientError` | `raise_error.rb:41` (status 408) · `producer.rb:124,214` (timeout local de RPC) |
+| `Conflict` | `ClientError` | `raise_error.rb:42` — status 409 |
+| `UnprocessableEntity` | `ClientError` | `raise_error.rb:44` — status 422. Parsea body, expone `error_messages` (busca clave `errors`); setea `raw_response` en el ctor |
+| `ServerError` | `Error` | `raise_error.rb:168` — 5xx no mapeado explícito |
+| `InternalServerError` | `ServerError` | `raise_error.rb:67`, `producer.rb:396` (JSON inválido) — status 500 genérico |
+| `RemoteError` | `ServerError` | `raise_error.rb:63` — status 5xx con `body['bug_bunny_exception']`. Attrs: `original_class`, `original_message`, `original_backtrace` |
+
+> `ArgumentError`/`NameError` que levantan `client.rb:51`, `controller.rb:101,171`,
+> `routing/*` son de la API de configuración/programación (uso incorrecto del
+> dev), no del contrato runtime RPC — no se listan como contrato de error público.
+
+### b. Códigos de estado por superficie
+
+Mapeo `status → excepción` que aplica `Middleware::RaiseError#on_complete`
+(`raise_error.rb:32-48`) en el **lado cliente** del RPC. Referencia las
+operaciones de RFC-003 (`docs/api/`, hoy pendiente — ver §4), no las redefine.
+
+| superficie | status | excepción levantada | cuándo |
+|---|---|---|---|
+| Cliente RPC (`RaiseError`) | 200..299 | — (none) | éxito, flujo normal |
+| Cliente RPC | 400 | `BadRequest` | bad request |
+| Cliente RPC | 404 | `NotFound` / `RoutingError` | recurso / ruta RPC inexistente (`error_type: routing_error`) |
+| Cliente RPC | 406 | `NotAcceptable` | content negotiation |
+| Cliente RPC | 408 | `RequestTimeout` | timeout reportado por el remoto |
+| Cliente RPC | 409 | `Conflict` | conflicto de estado/negocio |
+| Cliente RPC | 422 | `UnprocessableEntity` | validación semántica del modelo remoto |
+| Cliente RPC | 500..599 | `RemoteError` / `InternalServerError` | error del worker (RemoteError si trae `bug_bunny_exception`) |
+| Cliente RPC | otro ≥500 | `ServerError` | 5xx no mapeado |
+| Cliente RPC | otro ≥400 | `ClientError` | 4xx no mapeado |
+| Productor (publish `:confirmed`) | n/a (AMQP) | `PublishNacked` / `PublishUnroutable` | NACK / return del broker — no es status HTTP |
+| Transporte (frontera gem) | n/a (AMQP) | `CommunicationError` | fallo de red/broker, envuelve `Bunny::Exception` |
+| **Worker (dispatch)** | **403** | — (no excepción; responde 403 + reject) | guard anti-RCE: clase enrutada no subclase de `BugBunny::Controller` (`consumer.rb:222-228`) |
+
+### c. Política por error
+
+Enriquecimiento `arch-enrich` (RFC-020 §c). Política **inferida** de semántica
+HTTP (RFC 9110) + AMQP — verificación humana pendiente (ver §3).
+
+| excepción | retriable | backoff | idempotencia | acción sugerida |
+|---|---|---|---|---|
+| `CommunicationError` | sí (fallo transitorio de red/broker) | sí (`network_recovery_interval`; Bunny auto-recover) | el retry de un **publish** puede duplicar salvo consumidor idempotente; un **read** RPC es seguro | reintentar con backoff; si persiste, circuit-break y alertar |
+| `ConfigurationError` | **no** (bug de config) | — | n/a | fail-fast al boot; corregir el bloque `configure` |
+| `PublishNacked` | sí, con cautela (NACK puede ser transitorio: disk full, replicación) | sí | el re-publish puede duplicar → requiere dedup aguas abajo | reintentar acotado; si persiste, alertar (problema del broker) |
+| `PublishUnroutable` | **no** (no hay binding para la routing key) | — | n/a | corregir routing key / topología de bindings; alertar (mensaje perdido) |
+| `BadRequest` (400) | **no** | — | n/a | corregir el request del cliente |
+| `NotFound` (404) | **no** | — | n/a | verificar recurso/identificador |
+| `RoutingError` (404) | **no** | — | n/a | corregir verbo/path; el servicio remoto no tiene esa ruta registrada |
+| `NotAcceptable` (406) | **no** | — | n/a | corregir content negotiation |
+| `RequestTimeout` (408) | sí (transitorio) | sí | el retry de un publish/RPC mutante puede duplicar → idempotencia requerida | reintentar con backoff; subir `rpc_timeout` si es crónico |
+| `Conflict` (409) | **no** sin resolver el conflicto | — | depende del flujo | resolver el estado en conflicto antes de reintentar |
+| `UnprocessableEntity` (422) | **no** (error semántico/validación) | — | n/a | corregir el payload; leer `error_messages` / `raw_response` |
+| `ClientError` (4xx genérico) | **no** (default 4xx) | — | n/a | inspeccionar status concreto |
+| `ServerError` (5xx genérico) | sí (transitorio) | sí | idempotencia requerida si la op muta estado | reintentar con backoff |
+| `InternalServerError` (500) | sí (transitorio) | sí | idem | reintentar con backoff; si persiste, escalar al dueño del worker |
+| `RemoteError` (500) | depende de `original_class` | depende | depende | inspeccionar `original_class`/`original_backtrace`; tratar como bug del worker remoto, no reintentar a ciegas |
+
+### d. Shape del payload de error
+
+**Lado worker → wire (lo que emite `Controller#handle_exception`, `controller.rb:224-233`)**
+ante una excepción no mapeada por `rescue_from`:
+
+```json
+{
+  "status": 500,
+  "headers": { },
+  "body": {
+    "error": "Internal Server Error",
+    "detail": "<exception.message>",
+    "type": "<exception.class.name>",
+    "bug_bunny_exception": {
+      "class": "<clase original>",
+      "message": "<mensaje original>",
+      "backtrace": ["<hasta 25 líneas>"]
+    }
+  }
+}
+```
+
+- El envelope `bug_bunny_exception` lo arma `RemoteError.serialize` (`remote_error.rb:29`);
+  también lo agrega `Consumer` cuando `status == 500 && exception` (`consumer.rb:325`).
+  Es lo que el cliente reconstruye como `RemoteError` (`raise_error.rb:61-64`).
+- `render status:, json:` (`controller.rb:242`) deja el shape del body de error de
+  dominio a criterio del worker — la gema no lo impone.
+
+**Lado cliente — materia prima expuesta (#52).** Toda excepción derivada de una
+respuesta RPC trae, vía `RaiseError#raise_typed` (`raise_error.rb:82-86`):
+
+- `e.status` → `Integer` (el código de la respuesta).
+- `e.raw_response` → `Hash | String | nil` (el cuerpo crudo, **sin interpretar**).
+  `nil` para errores no-RPC (`CommunicationError`, `ConfigurationError`).
+
+**Shapes que `format_error_message` reconoce para el `.message` humano**
+(`raise_error.rb:110-141`, best-effort, **NO contrato**):
+
+1. Envelope anidado: `{ "error": { "message": "..." } }` → extrae `error.message`.
+2. Shape plano histórico: `{ "error": "texto", "detail": "..." }` → `"texto - detail"`.
+3. Fallback: `body.to_json` (nunca `Hash#inspect`).
+
+`UnprocessableEntity` además expone `error_messages` (`exception.rb:219-263`):
+parsea el body, devuelve `parsed['errors']` por convención o el cuerpo completo.
+
+> **Seguridad (cruza RFC-017):** `raw_response` puede contener datos sensibles en
+> `details`. La gema lo entrega crudo a propósito; **sanitizar antes de cualquier
+> sink** (Sentry/logs) filtrando `password|pass|passwd|secret|token|api_key|auth`
+> → `[FILTERED]` es responsabilidad del consumidor (`exception.rb:25-30`).
+
+## 3. Inferencias
+
+- **Guard anti-RCE = 403, no excepción.** El control de seguridad que valida la
+  herencia de la clase enrutada vive en `consumer.rb:222-228`: si la clase
+  resuelta no es subclase de `BugBunny::Controller`, el worker loguea
+  `consumer.security_violation`, responde **403 'Forbidden'** (`handle_fatal_error`)
+  y rechaza el mensaje sin requeue — **no levanta una excepción dedicada**. La ex
+  `BugBunny::SecurityError` (nunca levantada en ninguna ruta de código) fue
+  **eliminada como dead code**; el contrato real del unhappy path de RCE es el 403
+  (ver §b). `confidence: high` (verificado por grep exhaustivo + lectura del guard).
+- **§b superficies AMQP** (`PublishNacked`/`PublishUnroutable`/`CommunicationError`)
+  no tienen status HTTP: son señales del protocolo AMQP, no del envelope RPC. Se
+  listan como `n/a (AMQP)` para no forzar un código HTTP inventado.
+- **§c política (enrich):** la columna retriable/backoff/idempotencia/acción está
+  **inferida** de la semántica estándar (HTTP RFC 9110 para 4xx/5xx, comportamiento
+  AMQP para NACK/return/transporte), **no** de una política declarada en el código
+  del gem. `confidence: medium`. A confirmar con el dueño del código /
+  consumidores reales (sobre todo idempotencia de re-publish y el caso
+  `RemoteError`, que depende del `original_class` del worker). El gem **no impone**
+  retry: la decisión es del consumidor en su boundary.
+
+## 4. Cobertura y fronteras
+
+- **§a/§b/§d (estructura) + §c (enrich, política inferida) completas** al commit
+  ancla. §c marcada `confidence: medium` (ver §3).
+- **RFC-003 (`docs/api/`) pendiente:** §b referencia "superficie" de operaciones
+  pero la capa operaciones no está generada (dev-structure F2, ver `CLAUDE.md`).
+  Cuando se genere, §b debe cruzar las operaciones reales.
+- **Frontera con `consumed` (RFC-018):** este artefacto = errores que la gema
+  **emite**. Los errores de `Bunny::*` que la gema **consume** y envuelve en
+  `CommunicationError` son su mapeo error-proveedor→excepción; viven en
+  `docs/consumed/rabbitmq.md` §d (que referencia este catálogo, no lo redefine).
+- **Errores internos no-públicos** (rescatados adentro, no cruzan la frontera) y
+  los `ArgumentError`/`NameError` de mal-uso de la API de config quedan fuera:
+  no son contrato runtime.

data/docs/release/release.md

@@ -1,9 +1,9 @@
 # Release — bug_bunny
 
-> meta: artefacto release · RFC-014 (shape v2.0, `proposed`) · generado
-> manualmente (**piloto RFC-014** — suplemento gema, valida patrón 1 +
-> per-repo-visible) · anclado a `.github/workflows/release.yml`, `*.gemspec`,
-> `lib/bug_bunny/version.rb`, `CHANGELOG.md`, git · fecha 2026-06-01 · cobertura:
+> meta: artefacto release · RFC-014 (`accepted`) · generado por `arch-structure`
+> + `arch-enrich` (híbrido RFC-014 §2; nació como piloto manual #51, re-anclado
+> a la RFC vigente) · anclado a `.github/workflows/release.yml`, `*.gemspec`,
+> `lib/bug_bunny/version.rb`, `CHANGELOG.md`, git · fecha 2026-06-30 · cobertura:
 > completa (régimen gema: build→publish, §e/f/g n/a).
 
 ## 1. Resumen
@@ -20,9 +20,9 @@ out-of-repo).
 
 ### a. Hecho verificable
 
-- **Convención de versión:** SemVer `vX.X.X`. Actual: **4.18.0**.
-- **Source of truth:** tag remoto (`v4.18.0`) + **triple mirror**
-  `lib/bug_bunny/version.rb` (`VERSION = '4.18.0'`) ← `bug_bunny.gemspec:7`
+- **Convención de versión:** SemVer `vX.X.X`. Actual: **4.19.0**.
+- **Source of truth:** tag remoto (`v4.19.0`) + **triple mirror**
+  `lib/bug_bunny/version.rb` (`VERSION = '4.19.0'`) ← `bug_bunny.gemspec:7`
   (`spec.version = BugBunny::VERSION`).
 - **Changelog canónico:** `CHANGELOG.md` único.
 - **Patrón de trigger:** `gema-tag` (patrón 1).
@@ -33,7 +33,7 @@ out-of-repo).
 
 - **Convención:** SemVer `vX.X.X` (**con `v`** — distinto al servicio).
 - **Source of truth:** tag remoto canónico (`git tag --sort=-v:refname` →
-  `v4.18.0`).
+  `v4.19.0`).
 - **Mirror:** `lib/bug_bunny/version.rb` (`VERSION`), leído por
   `bug_bunny.gemspec:7` (`spec.version = BugBunny::VERSION`).
   `required_ruby_version >= 2.6.0` (`bug_bunny.gemspec:17`).
@@ -58,7 +58,7 @@ out-of-repo).
   `on: push: tags: ['v*']` → `ruby/setup-ruby@v1` → `gem build *.gemspec` +
   `gem push *.gem` (auth `secrets.RUBYGEMS_API_KEY`). Auditable y versionado con
   el código; se ancla a `file:line`, no se referencia como caja negra.
-- **Consumo:** los servicios la pinnean por versión (`gem "bug_bunny", "~> 4.18.0"`)
+- **Consumo:** los servicios la pinnean por versión (`gem "bug_bunny", "~> 4.19.0"`)
   desde RubyGems — **no** git-source.
 
 ### e. Deploy / publish
@@ -80,7 +80,7 @@ procedimiento per-repo porque no vive acá. Una versión yankeada se anotaría e
 ### h. Dependencias de deploy inter-servicio
 
 - **Consumidores** (cruza RFC-018): servicios del fleet la pinnean
-  `~> 4.18.0` (semántica minor-compatible). Un cambio de contrato del gem
+  `~> 4.19.0` (semántica minor-compatible). Un cambio de contrato del gem
   (ej. el behavior-change de `4.18.0` — `Bunny::Exception` → `CommunicationError`)
   obliga a los consumidores a migrar; el `CHANGELOG.md` lo documenta como
   breaking note. **Orden de deploy:** los consumidores adoptan al hacer `bundle

data/docs/test/test.md

@@ -0,0 +1,110 @@
+# Test — bug_bunny
+
+> meta: artefacto test · RFC-013 · generado `arch-structure` (§a-§d) +
+> `arch-enrich` (§e-§h) · anclado a `24ea397`, `Rakefile`, `bug_bunny.gemspec`,
+> `spec/spec_helper.rb`, `spec/support/integration_helper.rb`,
+> `.github/workflows/main.yml`, `CHANGELOG.md` · fecha 2026-06-30 · cobertura:
+> §a-§d (estructura) + §e-§h (enrich, anclado a specs/CHANGELOG) completas.
+
+## 1. Resumen
+
+Suite principal **RSpec** (`spec/`, 22 specs: 15 unit + 7 integration). Tarea
+`:test` legacy de **Minitest** (`test/`, 2 archivos) fuera del default y del CI.
+CI corre `bundle exec rake` (= `:spec`) en Ruby 3.4.4. Sin coverage tool
+configurado.
+
+## 2. Cuerpo
+
+### a. Suites, frameworks y niveles
+
+| framework | dir | nivel | nº | propósito |
+|---|---|---|---|---|
+| **RSpec** `~> 3.0` | `spec/unit/` | unit | 15 | client/session pool, configuration, consumer, producer, controller, raise_error, remote_error, request, route, observability, otel, resource, middleware |
+| **RSpec** | `spec/integration/` | integration | 7 | client, consumer_middleware, controller, error_handling, infrastructure, publisher_confirms, resource — **requieren RabbitMQ real** (usan `BugBunny.create_connection` + pool) |
+| **Minitest** `~> 5.0` (+ `mocha`, `minitest-reporters`) | `test/integration/` | integration (legacy) | 2 | `manual_client_test.rb`, `infrastructure_test.rb` — tarea `:test`, **no** en default ni CI |
+
+Sin tags declarados (`:slow`/`:js`) en la config de RSpec.
+
+### b. Comando de corrida
+
+| objetivo | comando | qué corre |
+|---|---|---|
+| default / CI | `bundle exec rake` | tarea `:spec` (toda la suite RSpec) — `Rakefile:` `task default: :spec` |
+| solo unit | `bundle exec rake spec:unit` | `spec/unit/**/*_spec.rb` |
+| solo integration | `bundle exec rake spec:integration` | `spec/integration/**/*_spec.rb` (requiere broker) |
+| Minitest legacy | `bundle exec rake test` | `test/**/*_test.rb` |
+| CI | `.github/workflows/main.yml` → `bundle exec rake` | matrix Ruby `3.4.4`, `ruby/setup-ruby@v1` + `bundler-cache`, on push `main` + PR |
+
+> Todas las tareas RSpec corren con `--require spec_helper` (`Rakefile`).
+
+### c. Fixtures / Factories
+
+- **Sin FactoryBot ni fixtures YAML.** El setup vive en `spec/spec_helper.rb`:
+  configura `BugBunny` (host/user/pass desde ENV con default `guest`), arma un
+  `ConnectionPool` de test (`TEST_POOL`, size 5) y declara rutas globales para
+  todos los specs (`resources :ping/:node/:user`, `get 'around'/'rescue'/'boom'/
+  'echo'`, `post 'events'`).
+- **Carga `.env`** si existe (parse manual, `spec_helper.rb`).
+- **Soporte:** `spec/support/integration_helper.rb` (helpers + `TEST_WORKER_QUEUE_OPTS`
+  para colas efímeras), `spec/support/bunny_mocks.rb` (mocks de Bunny para unit).
+- `exchange_options = { durable: false, auto_delete: true }` → exchanges efímeros
+  en test.
+
+### d. Configuración de coverage
+
+**n/a** — sin SimpleCov ni `.simplecov` ni `SimpleCov.start` en el repo. No hay
+umbral de coverage declarado.
+
+### e. Gaps de cobertura
+
+- **Integration specs no corren en CI:** `main.yml` no declara servicio RabbitMQ;
+  las 7 integration specs **se skipean** vía `rabbitmq_available?`
+  (`spec/support/integration_helper.rb:14`, ver `publisher_confirms_spec.rb:10`).
+  En CI solo se ejercitan las **15 unit specs** → el contrato AMQP real (publish/
+  consume/confirms contra broker) **no se valida en pipeline**, solo localmente
+  con broker. Gap relevante.
+- **Sin medición de cobertura:** no hay SimpleCov ni umbral → la cobertura no está
+  cuantificada (no se sabe el % de líneas ejercidas).
+
+### f. Contract-assessment
+
+¿Los tests cubren los contratos públicos? (RFC-020/018/012/003)
+
+| contrato | specs que lo cubren | veredicto |
+|---|---|---|
+| **Errores RFC-020** (status→excepción, materia prima) | `raise_error_spec`, `remote_error_spec`, `communication_error_wrapping_spec`, `error_handling_spec` (integration) | **bien cubierto** (unit) |
+| **Consumed RFC-018** (Bunny::Exception→`CommunicationError`) | `communication_error_wrapping_spec`, `client_session_pool_spec` | cubierto (unit) |
+| **Config RFC-012** (validaciones de `Configuration`) | `configuration_spec` | cubierto |
+| **Confirms** (`PublishNacked`/`PublishUnroutable`) | `producer_spec`, `publisher_confirms_spec` (integration) | parcial en CI (la parte integration skipea sin broker) |
+| **Operaciones/routing** (RFC-003, capa F2) | `route_spec`, `request_spec`, `controller_spec`, `controller_after_action_spec`, `resource_spec` | cubierto (unit) |
+
+### g. Link a incidente → test de regresión
+
+| incidente | test de regresión | ancla |
+|---|---|---|
+| **#52** (`status`/`raw_response` en toda la jerarquía + hardening de `format_error_message`) | `raise_error_spec` — comentarios explícitos "Alcance issue #52" | `spec/unit/raise_error_spec.rb:59,120,169` |
+| **#49** (leak de `Bunny::TCPConnectionFailedForAllHosts` en `try_create`) | `communication_error_wrapping_spec` — "Client#publish — TCP fail en try_create (issue #49 caso original)" | `spec/unit/communication_error_wrapping_spec.rb:41` |
+
+### h. PII en fixtures / factories
+
+- **Sin PII.** No hay fixtures con datos personales: `spec_helper` usa
+  placeholders (`guest`/`localhost`), las rutas de test son `ping`/`node`/`user`
+  **sin payloads de datos reales**, y `bunny_mocks.rb` mockea el driver. Cruza
+  RFC-026: nada que clasificar/anonimizar. `confidence: high`.
+
+## 3. Inferencias
+
+- **Doble framework:** RSpec es el primario (default + CI); Minitest (`test/`,
+  `mocha`, `minitest-reporters` en gemspec) es **legacy** — el comentario del
+  `Rakefile` lo declara explícito ("tests de integración legacy de Minitest").
+  `confidence: high`.
+- ~~CI on `master` pero la rama principal es `main` (drift de naming)~~ →
+  **resuelto** (`main.yml` ahora dispara `push: branches: [main]`). El trigger
+  `push` corre en la rama por default; `pull_request` cubre los PRs.
+
+## 4. Cobertura y fronteras
+
+- §a-§d (estructura) + §e-§h (enrich, anclado a specs/CHANGELOG) **completas**.
+- **Integration specs requieren un RabbitMQ vivo** y se skipean sin broker (§e) —
+  por eso no se ejercitan en CI.
+- **Contenido de cada test case** queda en el código, no se inventaria acá.

data/lib/bug_bunny/exception.rb

@@ -60,10 +60,6 @@ module BugBunny
   # Se levanta al final de {BugBunny.configure} si algún atributo no pasa las validaciones.
   class ConfigurationError < Error; end
 
-  # Error lanzado cuando ocurren un acceso no permitido a controladores.
-  # Protege contra vulnerabilidades de RCE validando la herencia de las clases enrutadas.
-  class SecurityError < Error; end
-
   # Error lanzado cuando el broker responde NACK a una publicación en modo `:confirmed`.
   #
   # Un NACK significa que el broker rechazó explícitamente el mensaje (ej: política de

data/lib/bug_bunny/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BugBunny
-  VERSION = '4.19.0'
+  VERSION = '5.0.0'
 end

data/skill/SKILL.md

@@ -415,8 +415,9 @@ Limitación de RSpec: `instance_double` valida que el método exista pero **no**
 **Causa:** No hubo respuesta en `config.rpc_timeout` segundos.
 **Resolución:** Verificar que el worker esté activo y que el controlador remoto no lance excepciones silenciosas.
 
-### BugBunny::SecurityError
+### Guard anti-RCE (403, no es excepción)
 **Causa:** El mensaje intenta ejecutar un controlador que no hereda de `BugBunny::Controller`.
+**Comportamiento:** El worker responde **403 Forbidden** + reject + log `event=consumer.security_violation` (`consumer.rb:222-228`); no levanta una excepción dedicada.
 **Resolución:** Verificar la jerarquía de controladores y que `config.controller_namespace` coincida.
 
 ### BugBunny::RouteNotFoundError (404)

data/skill/references/consumer.md

@@ -119,5 +119,5 @@ livenessProbe:
 |-----------|-----------|
 | Ruta no encontrada | 404 + log `event=consumer.route_not_found` |
 | Controller no encontrado (namespace) | 404 + log `event=consumer.controller_not_found` |
-| Controller no hereda de BugBunny::Controller | `SecurityError` |
+| Controller no hereda de BugBunny::Controller | 403 Forbidden + reject + log `event=consumer.security_violation` (guard anti-RCE) |
 | Excepción no capturada en controller | 500 + log `event=controller.unhandled_exception` con backtrace |

data/skill/references/errores.md

@@ -7,7 +7,6 @@ StandardError
 └── BugBunny::Error
     ├── BugBunny::CommunicationError
     ├── BugBunny::ConfigurationError
-    ├── BugBunny::SecurityError
     ├── BugBunny::PublishNacked
     ├── BugBunny::PublishUnroutable
     ├── BugBunny::ClientError (4xx)
@@ -58,9 +57,10 @@ message, details } }`), parsealo en el boundary del servicio desde
 **Validaciones:** host (String no vacío), port (1-65535), username/password (no nil), heartbeat (0-3600), rpc_timeout (>0), channel_prefetch (1-10000).
 **Resolución:** Revisar el bloque `BugBunny.configure` y corregir valores.
 
-### BugBunny::SecurityError
+### Guard anti-RCE (403, no es excepción)
 **Causa:** Un mensaje intenta ejecutar un controlador que no hereda de `BugBunny::Controller`.
-**Cuándo:** El consumer resuelve la clase pero falla la validación `is_a?(BugBunny::Controller)`.
+**Cuándo:** El consumer resuelve la clase (`constantize`) pero falla `controller_class < BugBunny::Controller` (`consumer.rb:222-228`).
+**Comportamiento:** El worker **no levanta una excepción** — loguea `event=consumer.security_violation`, responde **403 Forbidden** al caller RPC y rechaza el mensaje sin requeue.
 **Resolución:** Verificar que el controlador herede de `BugBunny::Controller` y que `config.controller_namespace` sea correcto.
 
 ### BugBunny::PublishNacked

data/skill/references/routing.md

@@ -69,7 +69,7 @@ El consumer resuelve el controlador concatenando:
 
 Ejemplo: namespace `:admin`, controller `:reports` → `BugBunny::Controllers::Admin::ReportsController`
 
-Valida que el controlador sea subclase de `BugBunny::Controller`. Si no, lanza `SecurityError`.
+Valida que el controlador sea subclase de `BugBunny::Controller` (guard anti-RCE). Si no, el worker loguea `consumer.security_violation`, responde **403 Forbidden** y rechaza el mensaje sin requeue (`consumer.rb:222-228`) — no levanta una excepción dedicada.
 
 ## Route Object
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bug_bunny
 version: !ruby/object:Gem::Version
-  version: 4.19.0
+  version: 5.0.0
 platform: ruby
 authors:
 - gabix
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-25 00:00:00.000000000 Z
+date: 2026-07-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny
@@ -229,13 +229,18 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- AGENTS.md
 - CHANGELOG.md
 - CLAUDE.md
 - README.md
 - Rakefile
 - docs/behavior/behavior.md
+- docs/config/configuracion.md
+- docs/consumed/rabbitmq.md
+- docs/errors/errors.md
 - docs/glossary/glossary.md
 - docs/release/release.md
+- docs/test/test.md
 - initializer_example.rb
 - lib/bug_bunny.rb
 - lib/bug_bunny/client.rb
@@ -308,7 +313,7 @@ metadata:
   homepage_uri: https://github.com/gedera/bug_bunny
   source_code_uri: https://github.com/gedera/bug_bunny
   changelog_uri: https://github.com/gedera/bug_bunny/blob/main/CHANGELOG.md
-  documentation_uri: https://github.com/gedera/bug_bunny/blob/v4.19.0/skill
+  documentation_uri: https://github.com/gedera/bug_bunny/blob/v5.0.0/skill
 post_install_message:
 rdoc_options: []
 require_paths: