bug_bunny 4.17.1 → 4.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50bb70f17d783b52abeb208bc362953c9494b61853f836da84f73552e3a76966
-  data.tar.gz: 37f9550b64942b1e544a6e7d593c1695f1293c6a1b488e1b0bec3179d1f3b7a4
+  metadata.gz: 8c751d42f963af2dc145005dba7b6245b0dc9fa549cacecb824e6a5cc2c3232d
+  data.tar.gz: c7c602f3f96a47a85080b287fd87435bb161abcab6b5358f51b45ed05fd1428a
 SHA512:
-  metadata.gz: 4733c50dcb6824c4e7d53bc0842e823b0674c13bf6cd9d963f99b6fa090166d083ca64cc6e65eba2fc29bff09be840772a6404fae19e62f3dd9b6dbcf56fc2d3
-  data.tar.gz: e9613f65b4bce0ad19aa8c19f259c6a3069ba4dfe185e4146a5992ddfbd20b3428816ed882e9d637f2b4a85d1d5d307094763bf8f3082900e8c6d9d3fe8a1fb7
+  metadata.gz: e8e1e583486fec890b5ccdedb77f99f1954f37e9a4217afe1aee0085ca8483f242a966643bcce5da5a7a180d0223850039a883ae9ce92b8be91a02c7beaac7b7
+  data.tar.gz: 71305eaf4dec9b4bf3fae7bf19bbb3fd997d75c409c6d5239d52030c1c7b5833f48f675f5bbcf187ef16334c0286f7a780675add36980c5b927ca592c68ab9d7

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [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.
+
+### Correcciones
+- **`Client#publish`/`#request`/`#send` leak de `Bunny::TCPConnectionFailedForAllHosts` (#49):** el TCP fail nacía en `ConnectionPool::TimedStack#try_create` dentro de `@pool.with`, antes de entrar al `Producer#confirmed` que ya envolvía con `rescue StandardError`. `Client#run_in_pool` ahora envuelve cualquier `Bunny::Exception` → `BugBunny::CommunicationError` (cubre también `Bunny::ConnectionClosedError` in-flight sobre conn rota mid-publish). `BugBunny.create_connection` también envuelve (Railtie, scripts, tests). YARD `@raise` actualizado. — @Gabriel
+
+### Mejoras internas
+- `Producer#confirmed` rescue estrechado de `rescue StandardError` a `rescue Bunny::Exception` — no traga bugs internos (`NoMethodError`, `KeyError`) bajo la etiqueta de fallo de transporte. — @Gabriel
+- `CommunicationError` docstring expandido: declara que envuelve cualquier `Bunny::Exception`, no solo TCP, y que `.cause` preserva la original. — @Gabriel
+- `Client#run_in_pool` refactor: extraído `execute_in_pool` privado para mantener `Metrics/AbcSize`. — @Gabriel
+
+### Documentación
+- `docs/behavior/behavior.md` refrescado scoped (RFC-001 §3.3.3 vía quality-code Paso 5): nota de contrato de error wrapping en flujos Fire-and-forget y Confirmed; nueva entrada en §3 Inferencias; verificación humana 2026-05-26. — @Gabriel
+- `README.md` y `skill/SKILL.md` re-indexados vía `dev-compose`: jerarquía de excepciones refinada, gotcha nuevo sobre errores de transporte 4.18+, descripción de `BugBunny::CommunicationError` en errores comunes. — @Gabriel
+
 ## [4.17.1] - 2026-05-19
 
 > Release docs-only sobre 4.17.0 — sin cambios en `lib/` ni API pública. Incorpora la familia de skills `dev-*` (RFC-001) y los artefactos de detalle version-locked (`docs/glossary`, `docs/behavior`) que viajan en el `.gem`.

data/README.md

@@ -377,7 +377,7 @@ BugBunny maps RabbitMQ responses to a semantic exception hierarchy, similar to h
 
 ```
 BugBunny::Error
-├── CommunicationError                  (network / channel failure)
+├── 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)

data/docs/behavior/behavior.md

@@ -1,6 +1,6 @@
 # Comportamiento — bug_bunny
 
-> meta: artefacto `comportamiento` · RFC-007 (cadencia incremental default / completo on-demand) · generado dev-enrich 1.3.0 (backfill on-demand) · anclado a `a5cdb10` · cobertura: completa (6 flujos) · verificado por humano 2026-05-18
+> meta: artefacto `comportamiento` · RFC-007 (cadencia incremental default / completo on-demand) · generado dev-enrich 1.3.0 (backfill on-demand) · anclado a `94de2b4` · cobertura: completa (6 flujos) · verificado por humano 2026-05-18 (base) · 2026-05-26 (refresco scoped: contrato de error wrapping post-#49)
 
 ## 1. Resumen
 
@@ -68,6 +68,8 @@ sequenceDiagram
 ```
 Contexto: `client.rb:129-134` → `producer.rb:47-51` → `publish_message producer.rb:146-161`.
 
+**Errores (contrato cliente):** cualquier `Bunny::Exception` que escape durante `@pool.with` (TCP fail en `try_create`, `ConnectionClosedError` in-flight, `ChannelAlreadyClosed`, etc.) se envuelve como `BugBunny::CommunicationError` en `Client#run_in_pool` (`client.rb:155-167`). La excepción original queda en `.cause`. Los callers del `Client` no rescatan tipos `Bunny::*`.
+
 ### Flujo: Confirmed + basic.return bridge
 ACK del broker síncrono; `basic.return` (mandatory unroutable) llega en el reader thread de Bunny y se puentea al hilo de publish vía `@pending_returns` + `Concurrent::Event` con ventana de tolerancia GVL.
 
@@ -92,7 +94,7 @@ sequenceDiagram
     P-->>CL: PublishUnroutable (o éxito si slot vacío)
     Note over RT,S: on_return corre antes del raise · su excepción se loggea (no propaga)
 ```
-Contexto: `producer.rb:72-93,200-216,281-345`; `session.rb:70-74,204-250`. Branches: ack→ok · nack→`PublishNacked` (`producer.rb:235`) · return→`PublishUnroutable` (`producer.rb:325`) · timeout→`RequestTimeout` (`producer.rb:214-215`).
+Contexto: `producer.rb:72-93,200-216,281-345`; `session.rb:70-74,204-250`. Branches: ack→ok · nack→`PublishNacked` (`producer.rb:235`) · return→`PublishUnroutable` (`producer.rb:325`) · timeout→`RequestTimeout` (`producer.rb:214-215`) · canal/conn AMQP rota (`Bunny::Exception`)→`CommunicationError` (envuelta por `Producer#confirmed` `producer.rb:87-90` y/o `Client#run_in_pool` `client.rb:155-167`; `.cause` preserva la original).
 
 ### Flujo: Consumer subscribe loop + reconnect + health
 Loop bloqueante infinito con backoff exponencial + jitter en error; health check en TimerTask separado, **acoplado flojo** vía estado de session.
@@ -166,6 +168,7 @@ Contexto: `middleware/stack.rb:31-47` (build L43-47, `reverse.inject`), `base.rb
 | Secuencias y `file:line` extraídos por el LLM del código a `a5cdb10`; 2ª pasada LLM corrigió 3 discrepancias (flujo middleware invertido, timeout RPC `producer.rb:124`, timeout confirmed `producer.rb:214-215`) | confirmed | **verificado por humano 2026-05-18** (invariante RFC-001 §3.3 satisfecho) |
 | Orden wire `basic.return → basic.ack` garantizado por AMQP; `RETURN_RACE_WINDOW_S` cubre GVL | declared (código) / inferred (garantía AMQP) | confirmar lectura de `producer.rb:299-308` + spec AMQP |
 | Health check acoplado flojo al loop vía cierre de session | inferred | confirmar `consumer.rb:340-361` vs `106-124` |
+| Frontera de error del Client: cualquier `Bunny::Exception` durante `@pool.with` (try_create o in-flight) → `BugBunny::CommunicationError` con `.cause` preservada (`client.rb:155-167`). `Producer#confirmed` rescate estrechado a `Bunny::Exception` (`producer.rb:87-90`) — no traga bugs Ruby. `BugBunny.create_connection` también envuelve (`bug_bunny.rb:96-99`). | declared (código post-#49) | confirmar lectura de `client.rb:155-167`, `producer.rb:87-90`, `bug_bunny.rb:96-99` + specs `communication_error_wrapping_spec.rb` |
 
 ## 4. Cobertura y fronteras
 
@@ -173,4 +176,4 @@ Contexto: `middleware/stack.rb:31-47` (build L43-47, `reverse.inject`), `base.rb
 - **Lógica dispersa marcada (no fingida):** health check (thread aparte vía `Concurrent::TimerTask`, acople flojo con el loop sólo vía cierre de session). RFC-007: marcada, no diagramada como flujo limpio falso. (El orden onion del middleware NO es lógica dispersa: es mecanismo limpio y documentado en `stack.rb:37-39`.)
 - **Fuera de alcance:** estructura (operaciones/interfaz/topología) → dev-structure F2 (no implementado). Significado de términos → `glossary.md`. Datos → n/a (sin DB).
 - **Frescura:** PR que renombre/mueva un método citado → reviewer actualiza el diagrama y `file:line` en el mismo PR (RFC-001 §3.3).
-- **Verificación humana:** completada 2026-05-18 (invariante RFC-001 §3.3 satisfecho). Re-verificar en cada PR que toque un flujo citado (frescura).
+- **Verificación humana:** base completada 2026-05-18; refresco scoped 2026-05-26 (contrato de error wrapping post-#49 en Fire-and-forget y Confirmed; invariante RFC-001 §3.3 satisfecho). Re-verificar en cada PR que toque un flujo citado (frescura).

data/docs/release/release.md

@@ -0,0 +1,108 @@
+# 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:
+> completa (régimen gema: build→publish, §e/f/g n/a).
+
+## 1. Resumen
+
+Cómo se libera esta gema. **Patrón 1 (gema-tag):** push de tag `vX.X.X` → un
+**GitHub Actions workflow que vive en el repo** (`.github/workflows/release.yml`)
+→ `gem build` + `gem push` a **RubyGems público**. A diferencia de un servicio,
+el pipeline **no es opaco**: vive en `.github/`, es auditable y versionado con el
+código (`dueño: per-repo-visible`). Una gema **no despliega — publica**: §e
+(deploy), §f (ambientes), §g (rollback) son **n/a** (rollback = `gem yank`,
+out-of-repo).
+
+## 2. Cuerpo
+
+### 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`
+  (`spec.version = BugBunny::VERSION`).
+- **Changelog canónico:** `CHANGELOG.md` único.
+- **Patrón de trigger:** `gema-tag` (patrón 1).
+- **Salida:** gema publicada en **RubyGems público**.
+- **Deploy / ambientes / rollback:** **n/a** (gema publica, no despliega).
+
+### b. Versionado
+
+- **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`).
+- **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`).
+- **Política de divergencia:** `gem-release` lee el tag remoto; si `version.rb`
+  difiere → warn (posible release sin taguear). El bump se calcula sobre el tag.
+
+### c. Changelog
+
+- **Canónico único:** `CHANGELOG.md` ✓.
+- **Formato:** `## [X.X.X] - YYYY-MM-DD` + nota de behavior-change si aplica +
+  categorías (`### Correcciones`), atribución `— @autor`, **link al issue**
+  (ej. `(#49)`). Cruza RFC-013 §h: el changelog ya referencia el incidente que
+  motivó el fix.
+
+### d. Trigger → pipeline → salida
+
+| Patrón | Trigger (señal per-repo) | Pipeline | Salida | Dueño |
+|---|---|---|---|---|
+| `gema-tag` | push tag `vX.X.X` | GH Actions `.github/workflows/release.yml` | gema en **RubyGems público** | **`per-repo-visible`** |
+
+- **Pipeline NO opaco:** `.github/workflows/release.yml` —
+  `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"`)
+  desde RubyGems — **no** git-source.
+
+### e. Deploy / publish
+
+**n/a (deploy)** — una gema no despliega. El "release" es **publish** a RubyGems,
+cubierto en §d. No hay ambiente de runtime propio.
+
+### f. Ambientes
+
+**n/a** — no hay `dev`/`staging`/`prod`. La única salida es la gema publicada.
+
+### g. Rollback
+
+**n/a en el repo** — el rollback de una gema es **`gem yank <version>`** en
+RubyGems (admin out-of-repo), no un cambio de código. No se documenta como
+procedimiento per-repo porque no vive acá. Una versión yankeada se anotaría en
+`CHANGELOG.md` (con su razón) si pasara.
+
+### 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
+  (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
+  update bug_bunny` — no hay deploy coordinado (cada servicio elige cuándo).
+
+### i. Contrato con la skill productora
+
+- **Skill:** `gem-release` (tag-based, **aplica** — patrón 1 emite tag).
+- **Qué espera del repo:** `lib/bug_bunny/version.rb` como source, `*.gemspec`
+  que lo lee, `CHANGELOG.md` canónico, tag `vX.X.X`, gate `quality-code` verde,
+  y el `.github/workflows/release.yml` que publica en el tag.
+- **Estado:** conforma — layout estándar de gema, workflow per-repo presente.
+
+## 3. Inferencias
+
+- Ninguna relevante: el pipeline de gema es **visible** (`.github/`), así que el
+  artefacto se ancla a archivos reales, no a inferencia sobre cajas negras.
+
+## 4. Cobertura y fronteras
+
+- Cobertura **completa** del régimen gema (build→publish). §e/f/g `n/a` honesto.
+- Contraste validado con el piloto servicio (`box_radius_manager`): allá el
+  pipeline es **opaco** (`fleet-link` Codefresh); acá es **per-repo-visible**
+  (GH Actions en el repo). Misma RFC, dos loci de dueño — el valor de la columna
+  `dueño` de §d.

data/lib/bug_bunny/client.rb

@@ -138,9 +138,19 @@ module BugBunny
     # Ejecuta la lógica de envío dentro del contexto del Pool.
     # Mapea los argumentos al objeto Request y ejecuta la cadena de middlewares.
     #
+    # Cualquier `Bunny::Exception` que nazca durante la adquisición de la conexión
+    # (`@pool.with` → `try_create`) o durante operaciones sobre una conexión rota
+    # in-flight (canal cerrado, conn perdida) se envuelve en
+    # {BugBunny::CommunicationError}. Esto preserva el contrato de abstracción del
+    # gem: los callers del `Client` no deberían tener que rescatar tipos de
+    # `Bunny::*`. La excepción original queda accesible vía `.cause` (Ruby la
+    # preserva automáticamente al re-raisear dentro del `rescue`).
+    #
     # @param url [String] La ruta destino.
     # @param args [Hash] Argumentos pasados a los métodos públicos.
     # @yield [req] Bloque para configuración adicional del Request.
+    # @raise [BugBunny::CommunicationError] Si la conexión TCP/AMQP falla durante
+    #   la adquisición del slot del pool o durante la operación.
     def run_in_pool(url, args)
       req = build_request(url, args)
 
@@ -151,8 +161,19 @@ module BugBunny
       # de los keyword args. Evaluamos el warning sobre el estado final del Request.
       warn_return_raise_misuse(req)
 
-      # Ejecución dentro del Pool.
-      # Session y Producer se reutilizan por slot de conexión (ver #session_for / #producer_for).
+      execute_in_pool(req)
+    rescue BugBunny::Error
+      raise
+    rescue Bunny::Exception => e
+      raise BugBunny::CommunicationError, "AMQP failure on path=#{req&.path}: #{e.class}: #{e.message}"
+    end
+
+    # Ejecuta el Request dentro del Pool. Session y Producer se reutilizan por
+    # slot de conexión (ver #session_for / #producer_for).
+    #
+    # @param req [BugBunny::Request]
+    # @return [Hash] Respuesta del producer.
+    def execute_in_pool(req)
       @pool.with do |conn|
         session  = session_for(conn)
         producer = producer_for(conn, session)

data/lib/bug_bunny/exception.rb

@@ -5,10 +5,55 @@ require 'json'
 module BugBunny
   # Clase base para todas las excepciones lanzadas por la gema BugBunny.
   # Permite capturar cualquier error de la librería con un `rescue BugBunny::Error`.
-  class Error < ::StandardError; end
+  #
+  # Para los errores derivados de una respuesta RPC (los que levanta
+  # {BugBunny::Middleware::RaiseError}), expone de forma uniforme la **materia
+  # prima** del error: el `status` y el `raw_response` (cuerpo crudo). La gema es
+  # **agnóstica al payload**: no interpreta la estructura del cuerpo de error: es
+  # el boundary de cada servicio quien lee `raw_response` y decide la semántica
+  # de dominio (códigos, detalles de validación, etc.).
+  #
+  # @example Leer la materia prima en el boundary del servicio
+  #   rescue BugBunny::Error => e
+  #     e.status       # => 409
+  #     e.raw_response # => { "error" => { "code" => "...", "message" => "...", "details" => {} } }
+  class Error < ::StandardError
+    # @return [Hash, String, nil] El cuerpo crudo de la respuesta de error, tal
+    #   como llegó por el wire. `nil` para errores que no provienen de una
+    #   respuesta RPC (ej: {CommunicationError}, {ConfigurationError}).
+    #
+    # @note **No loguear ni enviar a sinks (Sentry/logs) sin sanitizar.** El
+    #   cuerpo crudo puede contener datos sensibles (p. ej. en `details`). Antes
+    #   de cualquier sink, filtrar las claves sensibles del fleet
+    #   (`password|pass|passwd|secret|token|api_key|auth`) → `[FILTERED]`. La
+    #   gema entrega el cuerpo crudo a propósito; sanitizarlo es responsabilidad
+    #   del consumidor.
+    attr_accessor :raw_response
+
+    # @return [Integer, nil] El código de estado de la respuesta que originó el
+    #   error (ej: 400, 404, 409, 422, 500). `nil` para errores que no provienen
+    #   de una respuesta RPC.
+    attr_accessor :status
+  end
 
-  # Error lanzado cuando ocurren problemas de red o conexión con RabbitMQ.
-  # Suele envolver excepciones nativas de la gema `bunny` (ej: TCP connection failure).
+  # Error lanzado cuando ocurren problemas de red, conexión o protocolo AMQP con RabbitMQ.
+  #
+  # Envuelve cualquier `Bunny::Exception` (TCP fail, auth fail, canal cerrado,
+  # `PreconditionFailed`, `ConnectionClosedError`, etc.) en las fronteras de
+  # abstracción del gem — `BugBunny.create_connection`, `BugBunny::Client#publish` /
+  # `#request` / `#send`, y `BugBunny::Producer#confirmed`. Los callers no deberían
+  # rescatar tipos de `Bunny::*` directamente: con `rescue BugBunny::CommunicationError`
+  # alcanza para cubrir cualquier fallo de transporte/broker.
+  #
+  # La excepción original queda accesible vía `.cause` (Ruby la preserva
+  # automáticamente al re-raisear dentro del `rescue`).
+  #
+  # @example
+  #   begin
+  #     client.publish('evt', exchange: 'x', body: payload)
+  #   rescue BugBunny::CommunicationError => e
+  #     logger.error("publish failed: #{e.message} cause=#{e.cause&.class}")
+  #   end
   class CommunicationError < Error; end
 
   # Error lanzado cuando la configuración de la gema es inválida.
@@ -175,8 +220,9 @@ module BugBunny
     # @return [Hash, Array, String] Los mensajes de error listos para ser iterados.
     attr_reader :error_messages
 
-    # @return [String, Hash] El cuerpo crudo de la respuesta original.
-    attr_reader :raw_response
+    # `raw_response` y `status` se heredan de {BugBunny::Error} (poblados por
+    # {BugBunny::Middleware::RaiseError}); `raw_response` además se setea acá en
+    # el constructor para mantener el comportamiento histórico.
 
     # Inicializa la excepción procesando el cuerpo de la respuesta.
     #

data/lib/bug_bunny/middleware/raise_error.rb

@@ -34,71 +34,125 @@ module BugBunny
         body = response['body']
 
         case status
-        when 200..299
-          nil # Flujo normal (Success)
-        when 400
-          raise BugBunny::BadRequest, format_error_message(body)
-        when 404
-          raise_not_found(body)
-        when 406
-          raise BugBunny::NotAcceptable
-        when 408
-          raise BugBunny::RequestTimeout
-        when 409
-          raise BugBunny::Conflict, format_error_message(body)
-        when 422
-          # Pasamos el body crudo; UnprocessableEntity lo procesará en exception.rb
-          raise BugBunny::UnprocessableEntity, body
-        when 500..599
-          if body.is_a?(Hash) && body['bug_bunny_exception']
-            exception_data = body['bug_bunny_exception']
-            raise BugBunny::RemoteError.new(
-              exception_data['class'],
-              exception_data['message'],
-              exception_data['backtrace'] || []
-            )
-          end
-          raise BugBunny::InternalServerError, format_error_message(body)
-        else
-          handle_unknown_error(status, body)
+        when 200..299 then nil # Flujo normal (Success)
+        when 400 then raise_typed(BugBunny::BadRequest.new(format_error_message(body)), status, body)
+        when 404 then raise_not_found(status, body)
+        when 406 then raise_typed(BugBunny::NotAcceptable.new, status, body)
+        when 408 then raise_typed(BugBunny::RequestTimeout.new, status, body)
+        when 409 then raise_typed(BugBunny::Conflict.new(format_error_message(body)), status, body)
+        # Pasamos el body crudo; UnprocessableEntity lo procesará en exception.rb
+        when 422 then raise_typed(BugBunny::UnprocessableEntity.new(body), status, body)
+        when 500..599 then raise_server_error(status, body)
+        else handle_unknown_error(status, body)
         end
       end
 
       private
 
-      # Formatea el cuerpo de la respuesta de error para que sea legible en las excepciones.
+      # Levanta el error de servidor (5xx). Si el worker remoto serializó su
+      # excepción en `bug_bunny_exception`, propaga un {BugBunny::RemoteError} con
+      # la traza original; si no, un {BugBunny::InternalServerError} genérico.
       #
-      # Prioriza la convención `{ "error": "...", "detail": "..." }`. Si la respuesta no
-      # sigue esta convención, convierte el Hash completo a un JSON string para mantenerlo legible.
+      # @param status [Integer] El código de estado (rango 500..599).
+      # @param body [Hash, String, nil] El cuerpo crudo de la respuesta.
+      # @raise [BugBunny::RemoteError] Si el cuerpo trae `bug_bunny_exception`.
+      # @raise [BugBunny::InternalServerError] Para 5xx genéricos.
+      def raise_server_error(status, body)
+        if body.is_a?(Hash) && body['bug_bunny_exception']
+          data = body['bug_bunny_exception']
+          remote = BugBunny::RemoteError.new(data['class'], data['message'], data['backtrace'] || [])
+          raise_typed(remote, status, body)
+        end
+
+        raise_typed(BugBunny::InternalServerError.new(format_error_message(body)), status, body)
+      end
+
+      # Puebla la materia prima del error (`status` + `raw_response`) en la
+      # excepción y la levanta. Aplica de forma uniforme a **todas** las clases de
+      # error derivadas de una respuesta RPC, no solo a {BugBunny::UnprocessableEntity}.
+      #
+      # La gema es agnóstica al payload: entrega el cuerpo crudo tal cual para que
+      # el boundary del servicio lo interprete; no parsea su estructura.
+      #
+      # @param error [BugBunny::Error] La excepción ya construida.
+      # @param status [Integer] El código de estado de la respuesta.
+      # @param body [Hash, String, nil] El cuerpo crudo de la respuesta.
+      # @raise [BugBunny::Error] Siempre levanta la excepción recibida.
+      # @return [void]
+      def raise_typed(error, status, body)
+        error.status = status
+        error.raw_response = body
+        raise error
+      end
+
+      # Formatea el cuerpo de la respuesta de error en un **string humano**
+      # best-effort para logs/Sentry. Es de mejor esfuerzo, **no un contrato**: la
+      # gema no expone `code`/`details` como API; quien los necesite los lee desde
+      # `raw_response` en el boundary del servicio.
+      #
+      # Soporta dos shapes del cuerpo, en orden de prioridad:
+      #
+      # 1. **Envelope anidado** `{ "error": { "message": "...", ... } }`: extrae
+      #    `error.message`.
+      # 2. **Shape plano** `{ "error": "texto", "detail": "..." }`: concatena
+      #    `error` + `detail`.
+      #
+      # Si ninguno aplica, cae a `body.to_json` para no volcar un `Hash#inspect`
+      # ilegible en los logs.
+      #
+      # @note Esta función **solo** arma el mensaje humano y no interpreta el
+      #   detalle estructurado del cuerpo (claves como `code`/`details`/`detail`).
+      #   Ese contenido vive en `raw_response` y lo interpreta el boundary del
+      #   servicio; la gema se mantiene agnóstica al payload.
       #
       # @param body [Hash, String, nil] El cuerpo de la respuesta.
-      # @return [String] Un mensaje de error limpio y estructurado.
+      # @return [String] Un mensaje de error limpio y legible.
       def format_error_message(body)
         return 'Unknown Error' if body.nil? || (body.respond_to?(:empty?) && body.empty?)
         return body if body.is_a?(String)
+        return body.to_json unless body.is_a?(Hash)
+
+        human_message_from(body) || body.to_json
+      end
 
-        # Si el worker devolvió un JSON con una key 'error' (nuestra convención en Controller)
-        if body.is_a?(Hash) && body['error']
-          detail = body['detail'] ? " - #{body['detail']}" : ''
-          "#{body['error']}#{detail}"
-        else
-          # Fallback: Convertir todo el Hash a JSON string para que se vea claro en Sentry/Logs
-          body.to_json
+      # Extrae el string humano del cuerpo según el shape, sin volcar Hashes.
+      #
+      # @param body [Hash] El cuerpo de la respuesta.
+      # @return [String, nil] El mensaje humano, o `nil` si el shape no lo provee.
+      # @api private
+      def human_message_from(body)
+        err = body['error']
+
+        # Envelope canónico anidado: { error: { message: "..." } }
+        if err.is_a?(Hash)
+          nested = err['message']
+          return nested if nested.is_a?(String) && !nested.empty?
+
+          return nil
         end
+
+        # Shape plano histórico: { error: "texto", detail: "..." }.
+        # Cualquier String (incluido "") entra por acá para preservar el
+        # comportamiento histórico (la key 'error' siempre fue truthy).
+        return nil unless err.is_a?(String)
+
+        detail = body['detail'] ? " - #{body['detail']}" : ''
+        "#{err}#{detail}"
       end
 
       # Distingue un error de routing (ruta/controller no existe en el servicio remoto)
       # de un 404 genérico de recurso no encontrado.
       #
+      # @param status [Integer] El código de estado (404).
       # @param body [Hash, String, nil] El cuerpo de la respuesta 404.
       # @raise [BugBunny::RoutingError] Si el consumer marcó `error_type: 'routing_error'`.
       # @raise [BugBunny::NotFound] Para 404 genéricos.
-      def raise_not_found(body)
+      def raise_not_found(status, body)
         if body.is_a?(Hash) && body['error_type'] == 'routing_error'
-          raise BugBunny::RoutingError, format_error_message(body)
+          raise_typed(BugBunny::RoutingError.new(format_error_message(body)), status, body)
         end
 
-        raise BugBunny::NotFound, format_error_message(body)
+        raise_typed(BugBunny::NotFound.new(format_error_message(body)), status, body)
       end
 
       # Maneja códigos de error genéricos no mapeados explícitamente en el `case`.
@@ -111,9 +165,9 @@ module BugBunny
         msg = format_error_message(body)
 
         if status >= 500
-          raise BugBunny::ServerError, "Server Error (#{status}): #{msg}"
+          raise_typed(BugBunny::ServerError.new("Server Error (#{status}): #{msg}"), status, body)
         elsif status >= 400
-          raise BugBunny::ClientError, "Client Error (#{status}): #{msg}"
+          raise_typed(BugBunny::ClientError.new("Client Error (#{status}): #{msg}"), status, body)
         end
       end
     end

data/lib/bug_bunny/producer.rb

@@ -86,8 +86,8 @@ module BugBunny
       { 'status' => 202, 'body' => nil }
     rescue BugBunny::Error
       raise
-    rescue StandardError => e
-      raise BugBunny::CommunicationError, "Publisher confirms failed: #{e.message}"
+    rescue Bunny::Exception => e
+      raise BugBunny::CommunicationError, "Publisher confirms failed: #{e.class}: #{e.message}"
     ensure
       teardown_return_listener(request, return_listener)
     end

data/lib/bug_bunny/version.rb

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

data/lib/bug_bunny.rb

@@ -80,7 +80,10 @@ module BugBunny
   # @option options [Integer] :continuation_timeout (15000) Timeout para operaciones RPC internas.
   #
   # @return [Bunny::Session] Una sesión de Bunny ya iniciada (`start` ya invocado).
-  # @raise [Bunny::TCPConnectionFailed] Si no se puede conectar al servidor.
+  # @raise [BugBunny::CommunicationError] Si no se puede establecer la conexión
+  #   (TCP fail, auth fail, vhost inválido, etc.). Envuelve cualquier
+  #   `Bunny::Exception` para preservar la frontera de abstracción del gem.
+  #   La excepción original queda en `.cause`.
   def self.create_connection(**options)
     conn_options = merge_connection_options(options)
     Bunny.new(conn_options).tap do |conn|
@@ -89,6 +92,10 @@ module BugBunny
       end
       conn.start
     end
+  rescue Bunny::Exception => e
+    raise BugBunny::CommunicationError,
+          "Failed to establish AMQP connection to #{conn_options[:host]}:#{conn_options[:port]}: " \
+          "#{e.class}: #{e.message}"
   end
 
   # Cierra la conexión global si existe.

data/skill/SKILL.md

@@ -19,7 +19,7 @@ Gema Ruby: capa de routing RESTful sobre AMQP/RabbitMQ. Microservicios se comuni
 
 ## Contrato resumido (piso mínimo)
 
-> Resume el contrato de **`bug_bunny` 4.17.0**. Suficiente para el uso típico sin abrir el detalle; el detalle version-locked está en [`../docs/behavior/behavior.md`](../docs/behavior/behavior.md) (6 flujos) y [`../docs/glossary/glossary.md`](../docs/glossary/glossary.md) (símbolos→significado). Antipatrones/API completa: más abajo (embebido interim, ver Cobertura y fronteras).
+> Resume el contrato de **`bug_bunny` 4.18.0**. Suficiente para el uso típico sin abrir el detalle; el detalle version-locked está en [`../docs/behavior/behavior.md`](../docs/behavior/behavior.md) (6 flujos) y [`../docs/glossary/glossary.md`](../docs/glossary/glossary.md) (símbolos→significado). Antipatrones/API completa: más abajo (embebido interim, ver Cobertura y fronteras).
 
 **Símbolos públicos clave**
 
@@ -31,7 +31,7 @@ Gema Ruby: capa de routing RESTful sobre AMQP/RabbitMQ. Microservicios se comuni
 | `BugBunny::Controller` | `before/around/after_action`, `rescue_from`, `render status:, json:` |
 | `BugBunny.routes.draw` | `resources :x` · `namespace` · `member`/`collection` |
 | `BugBunny.configure` | `host/port/username/password` · `rpc_timeout` (default 10) · `nack_raise`/`return_raise` (default `true`) · `on_return` |
-| Excepciones | `RemoteError` (500 con backtrace remoto) · `PublishNacked` · `PublishUnroutable` · `RequestTimeout` · `NotFound` · `UnprocessableEntity` |
+| Excepciones | `RemoteError` (500 con backtrace remoto) · `PublishNacked` · `PublishUnroutable` · `RequestTimeout` · `NotFound` · `UnprocessableEntity` · `CommunicationError` (envuelve cualquier `Bunny::Exception` — TCP/conn/canal; `.cause` preserva original) |
 
 **Uso típico**
 
@@ -54,6 +54,7 @@ client.publish('events', body: { type: 'x' })   # => { 'status' => 202 }
 - `confirmed:true + mandatory:true` con `return_raise` (default `true`) → `PublishUnroutable` si no rutea.
 - `BugBunny::Consumer.subscribe` requiere `connection:`. No correr el Consumer en threads de Puma (loop bloqueante).
 - `exchange_options: { durable: true }` debe matchear la declaración del consumer, o `Bunny::PreconditionFailed`.
+- **Errores de transporte (4.18+):** TCP fail, conn rota, canal cerrado → siempre `BugBunny::CommunicationError`. No rescatar `Bunny::TCPConnectionFailed`/`ConnectionClosedError` directo — quedó atrás de la frontera. La original sigue accesible vía `.cause`.
 
 ## Índice de artefactos (fuente de verdad)
 
@@ -431,8 +432,13 @@ Limitación de RSpec: `instance_double` valida que el método exista pero **no**
 **Resolución:** `rescue BugBunny::RemoteError => e` y acceder a `e.original_class`, `e.original_message`, `e.original_backtrace`. Revisar logs del consumer (`event=controller.unhandled_exception`).
 
 ### BugBunny::CommunicationError
-**Causa:** Fallo de conexión o reconexión agotada.
-**Resolución:** Verificar conectividad a RabbitMQ. Revisar `max_reconnect_attempts` y logs de reconexión.
+**Causa:** Fallo de transporte AMQP — envuelve cualquier `Bunny::Exception` que escape en la frontera del gem (`Client#publish`/`#request`/`#send`, `Producer#confirmed`, `BugBunny.create_connection`). Cubre TCP fail (`Bunny::TCPConnectionFailed`), conn rota in-flight (`ConnectionClosedError`), canal cerrado (`ChannelAlreadyClosed`), auth fail, etc. La excepción original queda en `.cause`.
+**Resolución:** Verificar conectividad a RabbitMQ (host/port/auth/vhost). Inspeccionar `e.cause` para clasificar el fallo concreto. Revisar `max_reconnect_attempts` y logs de reconexión.
+
+**Materia prima (desde 4.19):** todo `BugBunny::Error` de respuesta RPC expone
+`e.status` y `e.raw_response` (cuerpo crudo) de forma uniforme — no solo 422. La
+gema es agnóstica al payload: el envelope de dominio se parsea en el boundary del
+servicio. No loguear `raw_response` sin sanitizar.
 
 Ver catálogo completo en [Errores](references/errores.md).
 

data/skill/references/errores.md

@@ -22,6 +22,30 @@ StandardError
         └── BugBunny::RemoteError (500)
 ```
 
+## Materia prima del error (`status` + `raw_response`) — desde 4.19
+
+Todos los errores derivados de una respuesta RPC exponen de forma **uniforme**
+el `status` y el `raw_response` (cuerpo crudo), no solo `UnprocessableEntity`.
+La gema es **agnóstica al payload**: entrega el cuerpo crudo tal cual y el
+boundary del servicio decide la semántica de dominio (códigos, detalles, etc.).
+
+```ruby
+begin
+  client.request('clusters/42', method: :get)
+rescue BugBunny::Error => e
+  e.status       # => 409 (Integer, nil si el error no viene de una respuesta RPC)
+  e.raw_response # => cuerpo crudo tal como llegó por el wire (Hash/String/nil)
+end
+```
+
+> ⚠️ **No loguear `raw_response` crudo.** Puede contener datos sensibles. Filtrar
+> claves (`password|pass|passwd|secret|token|api_key|auth`) → `[FILTERED]` antes
+> de Sentry/logs. La gema lo entrega a propósito; sanitizar es del consumidor.
+
+Para consumir un envelope estructurado de dominio (ej. `{ error: { code,
+message, details } }`), parsealo en el boundary del servicio desde
+`e.raw_response` — la gema **no** expone `code`/`details` como contrato.
+
 ## Errores de Infraestructura
 
 ### BugBunny::CommunicationError
@@ -133,10 +157,15 @@ end
 
 ## Formato de Mensajes de Error
 
-El middleware `RaiseError` construye el mensaje así:
-1. Busca `{ "error": "...", "detail": "..." }` en el body.
-2. Si no encuentra, usa el Hash completo como JSON.
-3. Si el body está vacío, usa `"Unknown Error"`.
+El middleware `RaiseError` construye el `.message` humano (best-effort, para
+logs/Sentry — **no es contrato**) así:
+1. Envelope anidado `{ "error": { "message": "..." } }` → extrae `error.message`.
+2. Shape plano `{ "error": "...", "detail": "..." }` → concatena `error` + `detail`.
+3. Si ninguno aplica, usa el cuerpo completo como JSON (nunca un `Hash#inspect`).
+4. Si el body está vacío, usa `"Unknown Error"`.
+
+Para detalle estructurado (`code`/`details`), leé `e.raw_response` en el
+boundary del servicio (ver "Materia prima del error").
 
 ## Connection Pool Missing
 

data/skills.yml

@@ -2,34 +2,18 @@ mcps:
   - github
   - clickup
 skills:
+  multi-vendor-feedback:
   yard:
-    repo: sequre/ai_knowledge
   quality-code:
-    repo: sequre/ai_knowledge
   gem-release:
-    repo: sequre/ai_knowledge
   dev-structure:
-    repo: sequre/ai_knowledge
   dev-compose:
-    repo: sequre/ai_knowledge
   dev-enrich:
-    repo: sequre/ai_knowledge
   skill-feedback:
-    repo: sequre/ai_knowledge
   agent-issue:
-    repo: sequre/ai_knowledge
+  bug-report:
   dev-flow:
-    repo: sequre/ai_knowledge
   matrix-element:
-    repo: sequre/ai_knowledge
-    environment:
-      homeserver: "https://matrix.cloud.wispro.co"
-      auth_token: "${MATRIX_AUTH_TOKEN}"
-      rooms:
-        agents: "!VCHwQXgmXdyhhhPhoz:matrix.cloud.wispro.co"
-  documentation-writer:
-    repo: github/awesome-copilot
-    path: skills/documentation-writer
-  rabbitmq-expert:
-    repo: martinholovsky/claude-skills-generator
-    path: skills/rabbitmq-expert
+  # rabbitmq-expert:
+  #   repo: martinholovsky/claude-skills-generator
+  #   path: skills/rabbitmq-expert

data/spec/unit/communication_error_wrapping_spec.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'support/bunny_mocks'
+
+# Specs para el contrato de envoltura definido en issue #49:
+# cualquier `Bunny::Exception` que escape de las fronteras de abstracción del
+# gem (`BugBunny.create_connection`, `BugBunny::Client#publish`/`#request`/`#send`,
+# `BugBunny::Producer#confirmed`) debe re-raisearse como
+# `BugBunny::CommunicationError`, preservando la excepción original en `.cause`.
+RSpec.describe 'Bunny::Exception → BugBunny::CommunicationError wrapping' do
+  include BunnyMocks
+
+  describe 'BugBunny.create_connection' do
+    before { BugBunny.configuration ||= BugBunny::Configuration.new }
+
+    it 'envuelve Bunny::TCPConnectionFailedForAllHosts en CommunicationError' do
+      fake_session = instance_double(Bunny::Session)
+      allow(fake_session).to receive(:after_recovery_completed)
+      allow(fake_session).to receive(:start).and_raise(Bunny::TCPConnectionFailedForAllHosts)
+      allow(Bunny).to receive(:new).and_return(fake_session)
+
+      err = capture_error { BugBunny.create_connection(host: 'broker.invalid', port: 5672) }
+      expect(err).to be_a(BugBunny::CommunicationError)
+      expect(err.message).to match(/broker.invalid:5672/)
+      expect(err.cause).to be_a(Bunny::TCPConnectionFailed)
+    end
+
+    it 'envuelve cualquier Bunny::Exception, no solo TCP' do
+      fake_session = instance_double(Bunny::Session)
+      allow(fake_session).to receive(:after_recovery_completed)
+      allow(fake_session).to receive(:start).and_raise(Bunny::AuthenticationFailureError.new('guest', '/', 0))
+      allow(Bunny).to receive(:new).and_return(fake_session)
+
+      err = capture_error { BugBunny.create_connection }
+      expect(err).to be_a(BugBunny::CommunicationError)
+      expect(err.cause).to be_a(Bunny::AuthenticationFailureError)
+    end
+  end
+
+  describe 'Client#publish — TCP fail en try_create (issue #49 caso original)' do
+    it 'envuelve Bunny::TCPConnectionFailedForAllHosts levantado dentro de @pool.with' do
+      # Pool falso que levanta la excepción raw de bunny al adquirir slot —
+      # simula exactamente lo observado en producción en el stack trace del issue.
+      raising_pool = Object.new
+      raising_pool.define_singleton_method(:with) { |&_block| raise Bunny::TCPConnectionFailedForAllHosts }
+
+      client = BugBunny::Client.new(pool: raising_pool)
+
+      err = capture_error { client.publish('evt', exchange: 'x', exchange_type: 'direct', body: { a: 1 }) }
+      expect(err).to be_a(BugBunny::CommunicationError)
+      expect(err.message).to match(/AMQP failure on path=evt/)
+      expect(err.cause).to be_a(Bunny::TCPConnectionFailed)
+    end
+  end
+
+  describe 'Client — in-flight ConnectionClosedError' do
+    it 'envuelve Bunny::ConnectionClosedError levantado por el Producer' do
+      conn    = BunnyMocks::FakeConnection.new(true, BunnyMocks::FakeChannel.new(true))
+      pool    = Object.new.tap { |p| p.define_singleton_method(:with) { |&blk| blk.call(conn) } }
+      client  = BugBunny::Client.new(pool: pool)
+
+      allow_any_instance_of(BugBunny::Producer).to receive(:fire)
+        .and_raise(Bunny::ConnectionClosedError.new('connection lost'))
+
+      err = capture_error { client.publish('evt', exchange: 'x', exchange_type: 'direct', body: { a: 1 }) }
+      expect(err).to be_a(BugBunny::CommunicationError)
+      expect(err.message).to match(/AMQP failure/)
+      expect(err.cause).to be_a(Bunny::ConnectionClosedError)
+    end
+  end
+
+  describe 'Client — pass-through de BugBunny::Error' do
+    it 'no re-envuelve errores propios del gem (RequestTimeout, PublishNacked, etc.)' do
+      conn    = BunnyMocks::FakeConnection.new(true, BunnyMocks::FakeChannel.new(true))
+      pool    = Object.new.tap { |p| p.define_singleton_method(:with) { |&blk| blk.call(conn) } }
+      client  = BugBunny::Client.new(pool: pool)
+
+      allow_any_instance_of(BugBunny::Producer).to receive(:rpc)
+        .and_raise(BugBunny::RequestTimeout.new('timeout'))
+
+      expect { client.request('foo', method: :get, exchange: 'x', exchange_type: 'direct') }
+        .to raise_error(BugBunny::RequestTimeout)
+    end
+  end
+
+  describe 'Producer#confirmed — rescue limitado a Bunny::Exception' do
+    it 'no traga errores genéricos de Ruby (NoMethodError) como CommunicationError' do
+      producer = BugBunny::Producer.new(instance_double(BugBunny::Session))
+      allow(producer).to receive(:setup_return_listener).and_return(nil)
+      allow(producer).to receive(:teardown_return_listener)
+      allow(producer).to receive(:publish_message).and_raise(NoMethodError.new('bug interno'))
+
+      request = BugBunny::Request.new('evt').tap do |r|
+        r.exchange = 'x'
+        r.exchange_type = 'direct'
+        r.delivery_mode = :confirmed
+      end
+
+      expect { producer.confirmed(request) }.to raise_error(NoMethodError, 'bug interno')
+    end
+
+    it 'envuelve Bunny::Exception como CommunicationError' do
+      producer = BugBunny::Producer.new(instance_double(BugBunny::Session))
+      allow(producer).to receive(:setup_return_listener).and_return(nil)
+      allow(producer).to receive(:teardown_return_listener)
+      allow(producer).to receive(:publish_message)
+        .and_raise(Bunny::ChannelAlreadyClosed.new('closed', double(id: 1)))
+
+      request = BugBunny::Request.new('evt').tap do |r|
+        r.exchange = 'x'
+        r.exchange_type = 'direct'
+        r.delivery_mode = :confirmed
+      end
+
+      err = capture_error { producer.confirmed(request) }
+      expect(err).to be_a(BugBunny::CommunicationError)
+      expect(err.message).to match(/Publisher confirms failed/)
+      expect(err.cause).to be_a(Bunny::ChannelAlreadyClosed)
+    end
+  end
+
+  def capture_error
+    yield
+    nil
+  rescue StandardError => e
+    e
+  end
+end

data/spec/unit/producer_spec.rb

@@ -377,13 +377,21 @@ RSpec.describe BugBunny::Producer do
       expect { confirmed_producer.confirmed(req) }.to raise_error(BugBunny::RequestTimeout, /Timeout/)
     end
 
-    it 'envuelve errores del canal como BugBunny::CommunicationError' do
-      allow(mock_channel).to receive(:wait_for_confirms).and_raise(StandardError, 'boom')
+    it 'envuelve Bunny::Exception del canal como BugBunny::CommunicationError' do
+      allow(mock_channel).to receive(:wait_for_confirms)
+        .and_raise(Bunny::ChannelAlreadyClosed.new('boom', double(id: 1)))
 
       expect { confirmed_producer.confirmed(build_request) }
         .to raise_error(BugBunny::CommunicationError, /boom/)
     end
 
+    it 'no traga errores genéricos de Ruby (rescue es Bunny::Exception, no StandardError)' do
+      allow(mock_channel).to receive(:wait_for_confirms).and_raise(NoMethodError, 'bug interno')
+
+      expect { confirmed_producer.confirmed(build_request) }
+        .to raise_error(NoMethodError, 'bug interno')
+    end
+
     it 'propaga BugBunny::Error sin envolver' do
       allow(fake_exchange).to receive(:publish).and_raise(BugBunny::CommunicationError, 'chan dead')
 

data/spec/unit/raise_error_spec.rb

@@ -55,5 +55,181 @@ RSpec.describe BugBunny::Middleware::RaiseError do
         expect { middleware.on_complete(response) }.to raise_error(BugBunny::NotFound)
       end
     end
+
+    # Alcance issue #52: status + raw_response como materia prima en TODAS las
+    # clases de error, no solo en 422.
+    describe 'raw_response and status on every error class' do
+      def captured_error(response)
+        middleware.on_complete(response)
+        nil
+      rescue BugBunny::Error => e
+        e
+      end
+
+      {
+        400 => BugBunny::BadRequest,
+        409 => BugBunny::Conflict,
+        500 => BugBunny::InternalServerError
+      }.each do |status, klass|
+        context "when status is #{status}" do
+          let(:body) { { 'error' => 'boom' } }
+          let(:error) { captured_error('status' => status, 'body' => body) }
+
+          it "raises #{klass} with status and raw_response populated" do
+            expect(error).to be_a(klass)
+            expect(error.status).to eq(status)
+            expect(error.raw_response).to eq(body)
+          end
+        end
+      end
+
+      context 'when status is 404 (NotFound)' do
+        let(:body) { { 'error' => 'missing' } }
+        let(:error) { captured_error('status' => 404, 'body' => body) }
+
+        it 'populates status and raw_response' do
+          expect(error.status).to eq(404)
+          expect(error.raw_response).to eq(body)
+        end
+      end
+
+      context 'when status is 422 (UnprocessableEntity)' do
+        let(:body) { { 'errors' => { 'name' => ['blank'] } } }
+        let(:error) { captured_error('status' => 422, 'body' => body) }
+
+        it 'keeps raw_response/error_messages and adds status from base' do
+          expect(error).to be_a(BugBunny::UnprocessableEntity)
+          expect(error.status).to eq(422)
+          expect(error.raw_response).to eq(body)
+          expect(error.error_messages).to eq('name' => ['blank'])
+        end
+      end
+
+      context 'when status is unmapped (418)' do
+        let(:body) { { 'error' => 'teapot' } }
+        let(:error) { captured_error('status' => 418, 'body' => body) }
+
+        it 'populates status and raw_response on the generic ClientError' do
+          expect(error).to be_a(BugBunny::ClientError)
+          expect(error.status).to eq(418)
+          expect(error.raw_response).to eq(body)
+        end
+      end
+    end
+
+    # Alcance issue #52: hardening de format_error_message contra el envelope
+    # anidado para no volcar un Hash#inspect en .message.
+    describe 'message hardening against the nested canonical envelope' do
+      def captured_error(response)
+        middleware.on_complete(response)
+        nil
+      rescue BugBunny::Error => e
+        e
+      end
+
+      context 'when error is the nested canonical envelope { error: { message } }' do
+        let(:body) { { 'error' => { 'code' => 'shortname_taken', 'message' => 'shortname already taken', 'details' => {} } } }
+        let(:error) { captured_error('status' => 409, 'body' => body) }
+
+        it 'extracts the human message and does not dump the Hash' do
+          expect(error.message).to eq('shortname already taken')
+          expect(error.message).not_to include('=>')
+        end
+      end
+
+      context 'when the nested envelope lacks a usable message' do
+        let(:body) { { 'error' => { 'code' => 'x', 'details' => {} } } }
+        let(:error) { captured_error('status' => 409, 'body' => body) }
+
+        it 'falls back to JSON instead of Hash#inspect' do
+          expect(error.message).to eq(body.to_json)
+          expect(error.message).not_to include('=>')
+        end
+      end
+
+      context 'when error is the flat historical shape { error: string, detail: string }' do
+        let(:body) { { 'error' => 'boom', 'detail' => 'because reasons' } }
+        let(:error) { captured_error('status' => 400, 'body' => body) }
+
+        it 'keeps concatenating error and detail (backward compatible)' do
+          expect(error.message).to eq('boom - because reasons')
+        end
+      end
+
+      context 'when error is an empty string (backward-compat edge case)' do
+        let(:body) { { 'error' => '', 'detail' => 'x' } }
+        let(:error) { captured_error('status' => 400, 'body' => body) }
+
+        it 'preserves the historical concatenation instead of dumping JSON' do
+          expect(error.message).to eq(' - x')
+        end
+      end
+    end
+
+    # Alcance issue #52: casos borde y paths no cubiertos arriba.
+    describe 'edge cases and uncovered paths' do
+      def captured_error(response)
+        middleware.on_complete(response)
+        nil
+      rescue BugBunny::Error => e
+        e
+      end
+
+      context 'when 5xx carries a serialized remote exception (bug_bunny_exception)' do
+        let(:body) do
+          { 'bug_bunny_exception' => { 'class' => 'ActiveRecord::RecordNotFound',
+                                       'message' => 'User not found',
+                                       'backtrace' => ['app.rb:1'] } }
+        end
+        let(:error) { captured_error('status' => 500, 'body' => body) }
+
+        it 'raises RemoteError with status and raw_response populated' do
+          expect(error).to be_a(BugBunny::RemoteError)
+          expect(error.status).to eq(500)
+          expect(error.raw_response).to eq(body)
+          expect(error.original_class).to eq('ActiveRecord::RecordNotFound')
+        end
+      end
+
+      context 'when 422 carries the nested envelope (consumer parses from raw_response)' do
+        let(:body) { { 'error' => { 'code' => 'taken', 'message' => 'shortname already taken', 'details' => {} } } }
+        let(:error) { captured_error('status' => 422, 'body' => body) }
+
+        it 'keeps raw_response intact for the service boundary' do
+          expect(error).to be_a(BugBunny::UnprocessableEntity)
+          expect(error.status).to eq(422)
+          expect(error.raw_response).to eq(body)
+        end
+      end
+
+      context 'when status is 406 (no-arg constructor)' do
+        let(:body) { { 'error' => 'nope' } }
+        let(:error) { captured_error('status' => 406, 'body' => body) }
+
+        it 'still populates status and raw_response' do
+          expect(error).to be_a(BugBunny::NotAcceptable)
+          expect(error.status).to eq(406)
+          expect(error.raw_response).to eq(body)
+        end
+      end
+
+      context 'when status is 408 (no-arg constructor)' do
+        let(:error) { captured_error('status' => 408, 'body' => nil) }
+
+        it 'still populates status' do
+          expect(error).to be_a(BugBunny::RequestTimeout)
+          expect(error.status).to eq(408)
+        end
+      end
+
+      context 'when body is not a Hash nor a String (e.g. Array)' do
+        let(:body) { [1, 2, 3] }
+        let(:error) { captured_error('status' => 400, 'body' => body) }
+
+        it 'falls back to JSON without raising in the formatter' do
+          expect(error.message).to eq(body.to_json)
+        end
+      end
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bug_bunny
 version: !ruby/object:Gem::Version
-  version: 4.17.1
+  version: 4.19.0
 platform: ruby
 authors:
 - gabix
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-19 00:00:00.000000000 Z
+date: 2026-06-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny
@@ -235,6 +235,7 @@ files:
 - Rakefile
 - docs/behavior/behavior.md
 - docs/glossary/glossary.md
+- docs/release/release.md
 - initializer_example.rb
 - lib/bug_bunny.rb
 - lib/bug_bunny/client.rb
@@ -283,6 +284,7 @@ files:
 - spec/support/bunny_mocks.rb
 - spec/support/integration_helper.rb
 - spec/unit/client_session_pool_spec.rb
+- spec/unit/communication_error_wrapping_spec.rb
 - spec/unit/configuration_spec.rb
 - spec/unit/consumer_middleware_spec.rb
 - spec/unit/consumer_spec.rb
@@ -306,7 +308,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.17.1/skill
+  documentation_uri: https://github.com/gedera/bug_bunny/blob/v4.19.0/skill
 post_install_message:
 rdoc_options: []
 require_paths: