bug_bunny 4.18.0 → 5.0.0

data/docs/release/release.md

@@ -0,0 +1,108 @@
+# Release — bug_bunny
+
+> meta: artefacto release · RFC-014 (`accepted`) · generado por `arch-structure`
+> + `arch-enrich` (híbrido RFC-014 §2; nació como piloto manual #51, re-anclado
+> a la RFC vigente) · anclado a `.github/workflows/release.yml`, `*.gemspec`,
+> `lib/bug_bunny/version.rb`, `CHANGELOG.md`, git · fecha 2026-06-30 · cobertura:
+> completa (régimen gema: build→publish, §e/f/g n/a).
+
+## 1. Resumen
+
+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.19.0**.
+- **Source of truth:** tag remoto (`v4.19.0`) + **triple mirror**
+  `lib/bug_bunny/version.rb` (`VERSION = '4.19.0'`) ← `bug_bunny.gemspec:7`
+  (`spec.version = BugBunny::VERSION`).
+- **Changelog canónico:** `CHANGELOG.md` único.
+- **Patrón de trigger:** `gema-tag` (patrón 1).
+- **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.19.0`).
+- **Mirror:** `lib/bug_bunny/version.rb` (`VERSION`), leído por
+  `bug_bunny.gemspec:7` (`spec.version = BugBunny::VERSION`).
+  `required_ruby_version >= 2.6.0` (`bug_bunny.gemspec:17`).
+- **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.19.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.19.0` (semántica minor-compatible). Un cambio de contrato del gem
+  (ej. el behavior-change de `4.18.0` — `Bunny::Exception` → `CommunicationError`)
+  obliga a los consumidores a migrar; el `CHANGELOG.md` lo documenta como
+  breaking note. **Orden de deploy:** los consumidores adoptan al hacer `bundle
+  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/docs/test/test.md

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

data/lib/bug_bunny/exception.rb

@@ -5,7 +5,36 @@ 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, conexión o protocolo AMQP con RabbitMQ.
   #
@@ -31,10 +60,6 @@ module BugBunny
   # Se levanta al final de {BugBunny.configure} si algún atributo no pasa las validaciones.
   class ConfigurationError < Error; end
 
-  # Error lanzado cuando ocurren un acceso no permitido a controladores.
-  # Protege contra vulnerabilidades de RCE validando la herencia de las clases enrutadas.
-  class SecurityError < Error; end
-
   # Error lanzado cuando el broker responde NACK a una publicación en modo `:confirmed`.
   #
   # Un NACK significa que el broker rechazó explícitamente el mensaje (ej: política de
@@ -191,8 +216,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/version.rb

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

data/skill/SKILL.md

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

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

data/skill/references/errores.md

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

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

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