bug_bunny 4.18.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 030517babaaafccb4ac6b067e1c11ac1cf6d4a6a711919c8455c3dcfe6a79637
-  data.tar.gz: fb9a551e05882e05efc3cd23215773507ae6d5d2baab70681360c04100724d29
+  metadata.gz: e1076566b6a3b8c25f6f00fc624c92681e8db881ffc3b8d6640da3bb7158333b
+  data.tar.gz: 2510fe871ec6f32804dba3faa7f1110408656e8cff30d2c0d537c7d0b30e1686
 SHA512:
-  metadata.gz: a5c4fbaade4883c361a20e705155d2b60dc6b3e6e64905afe34b02a7a7016cd7913bfd9f1f2de09979d357f72b026dbdc3129ad871d128a1b9ee901628a096b6
-  data.tar.gz: fb7b8dd6f7b74dee3c6d13b789dd07ff3abaeda535680a1ab7ea4276269e40a238588403e5fd7c8d2cdb3188acd3b7889d867d4dffed6a19af45d91eefa68591
+  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,36 @@
 # 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.
+
+### Nuevas funcionalidades
+- **`status` + `raw_response` uniformes en toda la jerarquía (#52):** subidos a la base `BugBunny::Error` (`attr_accessor`) y poblados por `RaiseError.on_complete` en **todas** las clases de error, no solo `UnprocessableEntity`. El consumidor accede a `e.status` / `e.raw_response` de forma uniforme; la gema queda agnóstica al payload y el boundary del servicio interpreta el envelope de dominio. — @Gabriel
+
+### Correcciones
+- **`.message` ya no vuelca un `Hash#inspect` con el envelope anidado (#52):** ante `{ error: { code, message, details } }`, `format_error_message` extrae `error.message` best-effort en vez de interpolar el Hash; mantiene el shape plano histórico (incluido `error: ""`) y cae a JSON. Es solo el string humano para logs/Sentry, no contrato. — @Gabriel
+
+### Documentación
+- `skill/references/errores.md` y `skill/SKILL.md`: nueva sección "Materia prima del error" (`status`/`raw_response`), formato de `.message` endurecido y advertencia de sanitización (no loguear `raw_response` crudo). — @Gabriel
+- Piloto RFC-014: `docs/release/release.md` (suplemento de release de la gema) (#51) — @Gabriel
+
 ## [4.18.0] - 2026-05-26
 
 > Behavior change menor: cualquier `Bunny::Exception` que escape en la frontera del gem (TCP fail, conn rota, canal cerrado, auth fail) ahora se envuelve como `BugBunny::CommunicationError`. La excepción original queda accesible vía `.cause`. Callers que rescatan `Bunny::TCPConnectionFailed` directo deben migrar a `BugBunny::CommunicationError`. Callers que ya rescatan `BugBunny::Error` / `CommunicationError`: sin cambios.

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.