bug_bunny 4.11.1 → 4.13.0

data/skill/SKILL.md

@@ -15,6 +15,9 @@ Skill de conocimiento completo sobre BugBunny. Consultame para cualquier pregunt
 **Session** — `BugBunny::Session` envuelve canales de Bunny con thread-safety y double-checked locking.
 **RPC** — Patrón síncrono que usa la pseudo-cola `amq.rabbitmq.reply-to` para respuestas sin crear queues temporales.
 **Fire-and-Forget** — Patrón asíncrono donde el producer publica y continúa sin esperar respuesta. Retorna `{ 'status' => 202 }`.
+**Publisher Confirms** — Extensión de RabbitMQ que confirma al publisher que el broker recibió el mensaje. BugBunny lo expone como `confirmed: true` en `Client#publish`: el publish bloquea hasta `wait_for_confirms`. NACK del broker (rechazo explícito) levanta `BugBunny::PublishNacked` por default; configurable via `config.nack_raise = false` o `nack_raise: false` per request para volver al modo log-only.
+**Mandatory** — Flag de `basic.publish` que pide al broker retornar el mensaje al publisher si no es ruteable a ninguna cola. Se procesa via `basic.return` (no es respuesta del request).
+**basic.return** — Evento asincrónico que Bunny dispatcha por exchange (`Bunny::Exchange#on_return`). BugBunny registra un handler único por nombre de exchange al resolverlo en `Session#exchange` y lo delega a `Configuration#on_return` o al default que logea.
 **Resource** — ORM tipo ActiveRecord que mapea operaciones CRUD a llamadas AMQP.
 **Consumer** — Worker bloqueante que despacha mensajes a controladores mediante un Router.
 **Connection Pool** — Pool de conexiones (`connection_pool` gem) que comparte sessions entre threads. Cada slot cachea su `Session` y `Producer`.
@@ -59,7 +62,7 @@ Skill de conocimiento completo sobre BugBunny. Consultame para cualquier pregunt
 |---|---|
 | `BugBunny::Configuration` | Configuración global. Valida campos requeridos en `BugBunny.configure`. |
 | `BugBunny::Session` | Wrapper de canal Bunny. Declara exchanges y queues. Thread-safe con double-checked locking. |
-| `BugBunny::Producer` | Publica mensajes. Implementa RPC con `Concurrent::IVar` y direct reply-to. |
+| `BugBunny::Producer` | Publica mensajes. Implementa tres modos: `#fire` (async), `#confirmed` (sync con `wait_for_confirms`) y `#rpc` (direct reply-to + `Concurrent::IVar`). |
 | `BugBunny::Client` | API de alto nivel. Pool de conexiones y middleware stack (onion architecture). |
 | `BugBunny::Consumer` | Subscribe loop con health check. Rutea mensajes via `BugBunny.routes`. |
 | `BugBunny::ConsumerMiddleware::Stack` | Pipeline de middlewares antes de `process_message`. Thread-safe. |
@@ -126,6 +129,11 @@ BugBunny.configure do |config|
   config.rpc_reply_headers = -> { { 'X-Trace-Id' => Tracer.id } }
   config.on_rpc_reply = ->(h) { Tracer.hydrate(h['X-Trace-Id']) }
 
+  # Publisher Confirms — handler global para basic.return (mensajes mandatory no ruteados).
+  # Si es nil, BugBunny logea como `session.broker_return` con nivel :warn.
+  # Firma: ->(return_info, properties, body)
+  config.on_return = ->(ri, _props, body) { MyAlerts.unroutable(rk: ri.routing_key, body: body) }
+
   # Infraestructura (cascade level 2)
   config.exchange_options = { durable: true }
   config.queue_options = { auto_delete: false }
@@ -169,7 +177,13 @@ Genera rutas REST estándar (index, show, create, update, destroy) mapeadas a co
 
 ---
 
-## API: RPC vs Fire-and-Forget
+## API: Modos de Entrega
+
+| Modo | Espera | Uso | Método |
+|---|---|---|---|
+| `:rpc` | Reply del consumer remoto | Request-response síncrono | `client.request(...)` |
+| `:publish` | Nada | Logs, eventos best-effort | `client.publish(...)` |
+| `:confirmed` | ACK del broker (`wait_for_confirms`) | Auditoría, billing, eventos críticos | `client.publish(..., confirmed: true)` |
 
 **RPC síncrono** — Bloquea hasta respuesta. Usa `amq.rabbitmq.reply-to`. Timeout configurable.
 ```ruby
@@ -183,6 +197,19 @@ client.publish('events', method: :post, body: { type: 'order.placed' })
 # → { 'status' => 202, 'body' => nil }
 ```
 
+**Confirmed (Publisher Confirms)** — Bloquea hasta el ACK del broker. Garantía de entrega al broker (no al consumer remoto).
+```ruby
+client.publish('acct.start', exchange: 'acct_x', body: payload,
+               confirmed: true, mandatory: true, confirm_timeout: 0.5)
+# → { 'status' => 202, 'body' => nil }   # broker ACK confirmado
+# Si broker NACK: logea `producer.confirms_nacked` y raise BugBunny::PublishNacked
+#   (default — opt-out con config.nack_raise = false o nack_raise: false per request).
+# Si timeout: raise BugBunny::RequestTimeout.
+# Si mandatory + no ruteable: dispara `Configuration#on_return` (default: logea `session.broker_return`).
+```
+
+`Bunny::Channel#wait_for_confirms` no soporta timeout nativo en Bunny 2.x. BugBunny lo implementa lanzando la espera en un hilo auxiliar y usando `Concurrent::IVar#value(timeout)` como reloj.
+
 ---
 
 ## FAQ

data/skill/references/client-middleware.md

@@ -7,7 +7,7 @@ API de alto nivel para publicar mensajes. Usa un pool de conexiones y una pila d
 ### Métodos Principales
 
 ```ruby
-# RPC síncrono — bloquea hasta respuesta
+# RPC síncrono — bloquea hasta respuesta del consumer
 response = client.request('users/123', method: :get, timeout: 30)
 response = client.request('users', method: :post, body: { name: 'John' })
 # → { 'status' => 200, 'body' => {...} }
@@ -16,8 +16,17 @@ response = client.request('users', method: :post, body: { name: 'John' })
 client.publish('events/user_created', method: :post, body: { user_id: 42 })
 # → { 'status' => 202, 'body' => nil }
 
-# General con bloque
-client.send(url) { |req| req.delivery_mode = :publish }
+# Publisher Confirms — bloquea hasta ACK del broker (no del consumer)
+client.publish('acct.start', exchange: 'acct_x', body: payload,
+               confirmed: true, mandatory: true, confirm_timeout: 0.5)
+# → { 'status' => 202, 'body' => nil }
+
+# General con bloque — máximo control
+client.send(url) do |req|
+  req.delivery_mode = :confirmed
+  req.mandatory = true
+  req.confirm_timeout = 1.0
+end
 ```
 
 ### Argumentos de Request
@@ -34,12 +43,16 @@ client.send(url) { |req| req.delivery_mode = :publish }
 | `routing_key` | String | path | Override de routing key |
 | `exchange_options` | Hash | {} | Cascade level 3 |
 | `queue_options` | Hash | {} | Cascade level 3 |
+| `confirmed` | Boolean | `false` | En `Client#publish`, flipea `delivery_mode` a `:confirmed`. Bloquea hasta `wait_for_confirms`. |
+| `mandatory` | Boolean | `false` | Pide al broker retornar el mensaje si no es ruteable. Solo útil con `confirmed: true`. |
+| `confirm_timeout` | Float | `nil` | Segundos máximos a esperar el ACK. `nil` = espera indefinida. Excedido → `BugBunny::RequestTimeout`. |
+| `nack_raise` | Boolean | `nil` | Override per-request de `config.nack_raise`. `nil` = usa flag global. |
 
 ## Producer (bajo nivel)
 
-El `Producer` es usado internamente por el `Client`. Implementa los dos patrones de entrega.
+El `Producer` es usado internamente por el `Client`. Implementa tres patrones de entrega.
 
-### RPC
+### RPC (`Producer#rpc`)
 
 - Usa `amq.rabbitmq.reply-to` (direct reply-to pattern).
 - Tracking de `correlation_id` en `Concurrent::Map` (thread-safe).
@@ -47,11 +60,19 @@ El `Producer` es usado internamente por el `Client`. Implementa los dos patrones
 - Double-checked locking mutex para seguridad del listener.
 - Timeout lanza `BugBunny::RequestTimeout`.
 
-### Fire-and-Forget
+### Fire-and-Forget (`Producer#fire`)
 
 - Publica en el exchange y retorna `{ 'status' => 202 }` inmediatamente.
 - Sin confirmación de procesamiento.
 
+### Confirmed (`Producer#confirmed`)
+
+- Publica y bloquea hasta `channel.wait_for_confirms` del broker.
+- Bunny 2.x **no soporta timeout** nativo en `wait_for_confirms` — BugBunny envuelve la llamada en un hilo auxiliar y usa `Concurrent::IVar#value(timeout)` como reloj. Si `confirm_timeout` expira → `BugBunny::RequestTimeout`.
+- Si `wait_for_confirms` devuelve `false` (broker NACKea), se logea `producer.confirms_nacked` con `count` y `path`. Por default (`config.nack_raise = true`) levanta `BugBunny::PublishNacked` con `path` y `nacked_count`. Para opt-out: `config.nack_raise = false` o pasar `nack_raise: false` per request — en ese caso solo logea y retorna 202.
+- Si `mandatory: true` y el mensaje no es ruteable, el broker dispara `basic.return`. El handler se atacha vía `Bunny::Exchange#on_return` en `Session#exchange` la primera vez que se resuelve cada exchange (cacheado por nombre, una sola vez por canal) y delega a `Configuration#on_return` o al logger por default.
+- Errores del canal se envuelven en `BugBunny::CommunicationError`; errores `BugBunny::Error` pre-existentes se propagan sin envolver.
+
 ## Middleware Stack (Client-side, Onion Architecture)
 
 ```
@@ -135,15 +156,78 @@ req.body                  # Hash, Array, String o nil
 req.headers               # Hash custom
 req.params                # Hash query string
 req.full_path             # path + query string
-req.delivery_mode         # :rpc o :publish
+req.delivery_mode         # :rpc, :publish o :confirmed
 req.exchange              # String destino
 req.exchange_type         # 'direct', 'topic', 'fanout'
 req.correlation_id        # UUID auto-generado
 req.reply_to              # 'amq.rabbitmq.reply-to' (auto para RPC)
 req.timestamp             # Time.now.to_i
 req.content_type          # 'application/json'
+req.mandatory             # Boolean — solo modo :confirmed
+req.confirm_timeout       # Float|nil — solo modo :confirmed
+req.nack_raise            # Boolean|nil — override per-request de config.nack_raise (solo modo :confirmed)
 ```
 
+Cuando `mandatory == true`, `Request#amqp_options` inyecta `mandatory: true` en el hash que va a `basic_publish`.
+
+## Publisher Confirms y `basic.return`
+
+### Flujo
+
+```
+client.publish('x', confirmed: true, mandatory: true)
+   │
+   ▼
+Producer#confirmed
+   │
+   ├──> publish_message     (exchange.publish con mandatory: true)
+   │
+   ├──> wait_for_confirms!  (espera ACK del broker, con timeout opcional)
+   │
+   └──> handle_confirm_result
+            ├─ acked == true  → return { status: 202 }
+            └─ acked == false → log WARN producer.confirms_nacked
+                                  └─ raise BugBunny::PublishNacked  (si config.nack_raise || req.nack_raise)
+
+Asíncronamente, si el broker no pudo rutear:
+   broker ──basic.return──> Exchange#on_return ──> Session handler ──> Configuration#on_return
+                                                                   └──> default: log session.broker_return WARN
+```
+
+### `Configuration#on_return`
+
+El handler se registra **una sola vez por exchange** en `Session#exchange` (cuando `publisher_confirms: true`) usando `Bunny::Exchange#on_return`. Bunny dispatcha `basic.return` por exchange, no por canal, así que el handler vive en cada `Bunny::Exchange` resuelto vía cascada. `Session` cachea los exchanges ya configurados por nombre en `@configured_returns` para no re-registrar en cada publish; el set se limpia al recrear el canal.
+
+```ruby
+BugBunny.configure do |c|
+  c.on_return = ->(return_info, properties, body) {
+    # return_info: Bunny::ReturnInfo (reply_code, reply_text, exchange, routing_key)
+    # properties:  Bunny::MessageProperties
+    # body:        String (payload crudo)
+    MyAlerts.unroutable(rk: return_info.routing_key, body: body)
+  }
+end
+```
+
+Si `on_return` es `nil` (default), BugBunny logea:
+
+```
+component=bug_bunny event=session.broker_return reply_code=312
+   reply_text="NO_ROUTE" exchange=evt_x routing_key=acct.start body_size=64
+```
+
+Excepciones del callback se capturan y se logean como `session.on_return_failed` para no romper el hilo I/O de Bunny.
+
+### Cuándo usar `:confirmed`
+
+| Escenario | Modo recomendado |
+|---|---|
+| Logs, eventos best-effort | `:publish` |
+| Auditoría, billing, eventos críticos | `:confirmed` (con `mandatory: true` si es ruteable) |
+| Request-response síncrono | `:rpc` |
+
+`:confirmed` cuesta un round-trip al broker pero **no** al consumer remoto — más rápido que RPC, con garantía de entrega al broker. NACK del broker es raro (típicamente por confirm policies internas, disk full, replicación insuficiente) pero **sí** implica que el mensaje no fue aceptado. Por default BugBunny levanta `BugBunny::PublishNacked` para que el caller pueda escalar (ej: convertir a HTTP 503 y dejar que el sistema upstream reintente). Opt-out con `config.nack_raise = false` o `nack_raise: false` per request.
+
 ## Cascada de Configuración (3 niveles)
 
 ```ruby

data/skill/references/errores.md

@@ -8,6 +8,7 @@ StandardError
     ├── BugBunny::CommunicationError
     ├── BugBunny::ConfigurationError
     ├── BugBunny::SecurityError
+    ├── BugBunny::PublishNacked
     ├── BugBunny::ClientError (4xx)
     │   ├── BugBunny::BadRequest (400)
     │   ├── BugBunny::NotFound (404)
@@ -37,6 +38,12 @@ StandardError
 **Cuándo:** El consumer resuelve la clase pero falla la validación `is_a?(BugBunny::Controller)`.
 **Resolución:** Verificar que el controlador herede de `BugBunny::Controller` y que `config.controller_namespace` sea correcto.
 
+### BugBunny::PublishNacked
+**Causa:** El broker NACKea explícitamente una publicación en modo `:confirmed` (`Client#publish(..., confirmed: true)`). Indica que el mensaje no fue aceptado — disk full, replicación insuficiente, confirm policy interna, etc.
+**Cuándo:** `Producer#confirmed` detecta `wait_for_confirms == false`. Se levanta por default (`config.nack_raise = true`).
+**Atributos:** `path` (ruta del request) y `nacked_count` (cantidad de delivery tags NACKeados).
+**Resolución:** Para casos críticos (auditoría, billing, RADIUS accounting), dejar que la excepción bubble para que el caller upstream reintente (ej: HTTP 503 → retry). Para tolerar NACKs (eventos best-effort), `BugBunny.configuration.nack_raise = false` global o `nack_raise: false` per request — en ese caso solo se logea `producer.confirms_nacked`.
+
 ## Errores de Cliente (4xx)
 
 ### BugBunny::BadRequest (400)

data/skills.yml

@@ -2,43 +2,28 @@ mcps:
   - github
   - clickup
 skills:
-  skill-manager:
-    repo: sequre/ai_knowledge
-    scope: local
   yard:
     repo: sequre/ai_knowledge
-    scope: local
   quality-code:
     repo: sequre/ai_knowledge
-    scope: local
   gem-release:
     repo: sequre/ai_knowledge
-    scope: local
   skill-builder:
     repo: sequre/ai_knowledge
-    scope: local
-  ai-reports:
+  matrix-element:
     repo: sequre/ai_knowledge
-    scope: local
     environment:
-      space_id: "${AI_REPORTS_SPACE_ID}"
-      bug_reports_list_id: "${AI_REPORTS_BUG_REPORTS_LIST_ID}"
-      improvements_list_id: "${AI_REPORTS_IMPROVEMENTS_LIST_ID}"
-  agent-review:
+      homeserver: "https://matrix.cloud.wispro.co"
+      auth_token: "${MATRIX_AUTH_TOKEN}"
+      rooms:
+        agents: "!VCHwQXgmXdyhhhPhoz:matrix.cloud.wispro.co"
+  skill-feedback:
+    repo: sequre/ai_knowledge
+  agent-issue:
     repo: sequre/ai_knowledge
-    scope: local
-    environment:
-      space_id: "${AGENT_REVIEW_SAPCE_ID}"
-      list_id: "${AGENT_LIST_ID}"
   documentation-writer:
     repo: github/awesome-copilot
     path: skills/documentation-writer
-    scope: local
-  find-skills:
-    repo: vercel-labs/skills
-    path: skills/find-skills
-    scope: local
   rabbitmq-expert:
     repo: martinholovsky/claude-skills-generator
     path: skills/rabbitmq-expert
-    scope: local

data/spec/support/bunny_mocks.rb

@@ -3,11 +3,47 @@
 # Stubs livianos de Bunny para specs unitarios que no necesitan RabbitMQ real.
 
 module BunnyMocks
+  # Stub mínimo de `Bunny::Exchange`: cachea el bloque pasado a `on_return`
+  # (Bunny lo invoca al recibir un `basic.return` del broker) y permite que
+  # los specs disparen retornos sintéticos vía `fire_return`.
+  class FakeExchange
+    attr_reader :name, :type, :opts
+
+    def initialize(name, type, opts = {})
+      @name = name
+      @type = type
+      @opts = opts
+    end
+
+    def on_return(&block)
+      @on_return_handler = block
+    end
+
+    def publish(_payload, _opts = {}); end
+
+    def fire_return(return_info, properties, body)
+      @on_return_handler&.call(return_info, properties, body)
+    end
+  end
+
   FakeChannel = Struct.new(:open) do
     def open?       = open
     def close       = (self.open = false)
     def confirm_select; end
     def prefetch(_n); end
+
+    def topic(name, opts = {})   = exchange_for(name, 'topic', opts)
+    def direct(name, opts = {})  = exchange_for(name, 'direct', opts)
+    def fanout(name, opts = {})  = exchange_for(name, 'fanout', opts)
+    def headers(name, opts = {}) = exchange_for(name, 'headers', opts)
+    def default_exchange         = exchange_for('', 'direct', {})
+
+    private
+
+    def exchange_for(name, type, opts)
+      @exchanges ||= {}
+      @exchanges[name] ||= FakeExchange.new(name, type, opts)
+    end
   end
 
   FakeConnection = Struct.new(:open, :channel_to_return) do

data/spec/unit/client_session_pool_spec.rb

@@ -27,7 +27,7 @@ RSpec.describe BugBunny::Client, 'session pooling' do
   def client_with_pool(pool)
     client = described_class.new(pool: pool)
     # Stub Producer#rpc para que no toque RabbitMQ real
-    allow_any_instance_of(BugBunny::Producer).to receive(:rpc) do |_prod, req|
+    allow_any_instance_of(BugBunny::Producer).to receive(:rpc) do |_prod, _req|
       { 'status' => 200, 'body' => '{"ok":true}' }
     end
     allow_any_instance_of(BugBunny::Producer).to receive(:fire) do |_prod, _req|
@@ -115,7 +115,7 @@ RSpec.describe BugBunny::Client, 'session pooling' do
 
   describe 'thread-safety' do
     it 'múltiples threads con la misma conexión no generan Sessions duplicadas' do
-      conn   = fake_conn
+      conn = fake_conn
       # Pool siempre devuelve la misma conexión — simula concurrencia en el mismo slot
       pool = Object.new
       mutex = Mutex.new
@@ -138,6 +138,83 @@ RSpec.describe BugBunny::Client, 'session pooling' do
     end
   end
 
+  describe 'Delivery mode routing' do
+    def fake_conn_local
+      channel = BunnyMocks::FakeChannel.new(true)
+      BunnyMocks::FakeConnection.new(true, channel)
+    end
+
+    it 'publish con confirmed: true enruta a Producer#confirmed' do
+      conn = fake_conn_local
+      client = described_class.new(pool: fake_pool(conn))
+
+      confirmed_called = false
+      allow_any_instance_of(BugBunny::Producer).to receive(:confirmed) do |_prod, _req|
+        confirmed_called = true
+        { 'status' => 202, 'body' => nil }
+      end
+
+      client.publish('acct.start',
+                     exchange: 'x', exchange_type: 'direct', body: { a: 1 },
+                     confirmed: true)
+
+      expect(confirmed_called).to be(true)
+    end
+
+    it 'propaga mandatory y confirm_timeout al Request' do
+      conn = fake_conn_local
+      client = described_class.new(pool: fake_pool(conn))
+
+      captured = nil
+      allow_any_instance_of(BugBunny::Producer).to receive(:confirmed) do |_prod, req|
+        captured = req
+        { 'status' => 202, 'body' => nil }
+      end
+
+      client.publish('acct.start',
+                     exchange: 'x', exchange_type: 'direct',
+                     confirmed: true, mandatory: true, confirm_timeout: 0.5)
+
+      expect(captured.delivery_mode).to eq(:confirmed)
+      expect(captured.mandatory).to be(true)
+      expect(captured.confirm_timeout).to eq(0.5)
+    end
+
+    it 'publish sin confirmed: true sigue invocando #fire (backward compat)' do
+      conn = fake_conn_local
+      client = described_class.new(pool: fake_pool(conn))
+
+      fire_called = false
+      allow_any_instance_of(BugBunny::Producer).to receive(:fire) do |_prod, _req|
+        fire_called = true
+        { 'status' => 202, 'body' => nil }
+      end
+
+      client.publish('evt', exchange: 'x', exchange_type: 'direct', body: {})
+
+      expect(fire_called).to be(true)
+    end
+
+    it 'send con bloque permite setear delivery_mode = :confirmed' do
+      conn = fake_conn_local
+      client = described_class.new(pool: fake_pool(conn))
+
+      confirmed_called = false
+      allow_any_instance_of(BugBunny::Producer).to receive(:confirmed) do |_prod, _req|
+        confirmed_called = true
+        { 'status' => 202, 'body' => nil }
+      end
+
+      client.send('evt.x', exchange: 'x', exchange_type: 'direct') do |req|
+        req.delivery_mode = :confirmed
+        req.mandatory = true
+        req.confirm_timeout = 0.2
+      end
+
+      expect(confirmed_called).to be(true)
+    end
+  end
+
   describe 'Session no se cierra entre requests' do
     it 'no invoca close en la Session al terminar el request' do
       conn   = fake_conn

data/spec/unit/configuration_spec.rb

@@ -149,6 +149,31 @@ RSpec.describe BugBunny::Configuration do
     end
   end
 
+  describe 'on_return callback' do
+    it 'tiene default nil' do
+      expect(BugBunny::Configuration.new.on_return).to be_nil
+    end
+
+    it 'acepta un Proc' do
+      cb = ->(_, _, _) { :noop }
+      configure_with(on_return: cb)
+
+      expect(BugBunny.configuration.on_return).to be(cb)
+    end
+  end
+
+  describe 'nack_raise flag' do
+    it 'tiene default true (raise PublishNacked en NACK)' do
+      expect(BugBunny::Configuration.new.nack_raise).to be(true)
+    end
+
+    it 'acepta false para opt-out (modo legacy)' do
+      configure_with(nack_raise: false)
+
+      expect(BugBunny.configuration.nack_raise).to be(false)
+    end
+  end
+
   describe '.validate! directamente' do
     it 'es invocable directamente sobre la instancia' do
       config = BugBunny::Configuration.new

data/spec/unit/producer_spec.rb

@@ -184,4 +184,146 @@ RSpec.describe BugBunny::Producer do
       end
     end
   end
+
+  describe '#confirmed' do
+    let(:fake_exchange) { double('exchange') }
+
+    let(:mock_channel) do
+      ch = double('channel')
+      allow(ch).to receive(:publish)
+      allow(ch).to receive(:open?).and_return(true)
+      allow(ch).to receive(:wait_for_confirms).and_return(true)
+      allow(ch).to receive(:nacked_set).and_return(Set.new)
+      ch
+    end
+
+    let(:mock_session) do
+      s = instance_double(BugBunny::Session)
+      allow(s).to receive(:exchange).and_return(fake_exchange)
+      allow(s).to receive(:channel).and_return(mock_channel)
+      s
+    end
+
+    let(:confirmed_producer) { described_class.new(mock_session) }
+
+    before do
+      allow(confirmed_producer).to receive(:safe_log) do |level, event, **kwargs|
+        logged_events << { level: level, event: event, kwargs: kwargs }
+      end
+      allow(fake_exchange).to receive(:publish)
+    end
+
+    def build_request
+      req = BugBunny::Request.new('acct.start')
+      req.exchange = 'acct_x'
+      req.method = :post
+      req.body = { tenant: 42 }
+      req
+    end
+
+    it 'retorna { status: 202 } cuando el broker confirma' do
+      result = confirmed_producer.confirmed(build_request)
+
+      expect(result).to eq('status' => 202, 'body' => nil)
+    end
+
+    it 'invoca wait_for_confirms en el canal' do
+      confirmed_producer.confirmed(build_request)
+
+      expect(mock_channel).to have_received(:wait_for_confirms)
+    end
+
+    it 'publica con mandatory: true cuando el request lo activa' do
+      req = build_request
+      req.mandatory = true
+
+      confirmed_producer.confirmed(req)
+
+      expect(fake_exchange).to have_received(:publish).with(
+        anything,
+        hash_including(mandatory: true, routing_key: 'acct.start')
+      )
+    end
+
+    it 'NO logea producer.confirms_nacked cuando wait_for_confirms devuelve true' do
+      confirmed_producer.confirmed(build_request)
+
+      nack_event = logged_events.find { |e| e[:event] == 'producer.confirms_nacked' }
+      expect(nack_event).to be_nil
+    end
+
+    context 'cuando el broker NACKea (wait_for_confirms devuelve false)' do
+      before do
+        allow(mock_channel).to receive(:wait_for_confirms).and_return(false)
+        allow(mock_channel).to receive(:nacked_set).and_return(Set.new([1, 2]))
+      end
+
+      it 'levanta BugBunny::PublishNacked por default (config.nack_raise = true)' do
+        expect { confirmed_producer.confirmed(build_request) }.to raise_error(BugBunny::PublishNacked) do |err|
+          expect(err.path).to eq('acct.start')
+          expect(err.nacked_count).to eq(2)
+        end
+      end
+
+      it 'logea producer.confirms_nacked antes de levantar' do
+        expect { confirmed_producer.confirmed(build_request) }.to raise_error(BugBunny::PublishNacked)
+
+        nack_event = logged_events.find { |e| e[:event] == 'producer.confirms_nacked' }
+        expect(nack_event).not_to be_nil
+        expect(nack_event[:kwargs]).to include(count: 2, path: 'acct.start')
+      end
+
+      it 'no levanta si el request override `nack_raise = false`' do
+        req = build_request
+        req.nack_raise = false
+
+        result = confirmed_producer.confirmed(req)
+
+        expect(result).to eq('status' => 202, 'body' => nil)
+        expect(logged_events.find { |e| e[:event] == 'producer.confirms_nacked' }).not_to be_nil
+      end
+
+      it 'no levanta si la configuración global tiene `nack_raise = false`' do
+        allow(BugBunny.configuration).to receive(:nack_raise).and_return(false)
+
+        result = confirmed_producer.confirmed(build_request)
+
+        expect(result).to eq('status' => 202, 'body' => nil)
+      end
+
+      it 'el override per-request gana sobre la configuración global' do
+        allow(BugBunny.configuration).to receive(:nack_raise).and_return(false)
+        req = build_request
+        req.nack_raise = true
+
+        expect { confirmed_producer.confirmed(req) }.to raise_error(BugBunny::PublishNacked)
+      end
+    end
+
+    it 'levanta BugBunny::RequestTimeout si wait_for_confirms excede confirm_timeout' do
+      allow(mock_channel).to receive(:wait_for_confirms) {
+        sleep 1
+        true
+      }
+
+      req = build_request
+      req.confirm_timeout = 0.05
+
+      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')
+
+      expect { confirmed_producer.confirmed(build_request) }
+        .to raise_error(BugBunny::CommunicationError, /boom/)
+    end
+
+    it 'propaga BugBunny::Error sin envolver' do
+      allow(fake_exchange).to receive(:publish).and_raise(BugBunny::CommunicationError, 'chan dead')
+
+      expect { confirmed_producer.confirmed(build_request) }
+        .to raise_error(BugBunny::CommunicationError, 'chan dead')
+    end
+  end
 end

data/spec/unit/request_spec.rb

@@ -47,5 +47,34 @@ RSpec.describe BugBunny::Request do
 
       expect(request.amqp_options[:headers]['x-http-method']).to eq('POST')
     end
+
+    it 'omite :mandatory cuando no fue activado' do
+      expect(request.amqp_options).not_to have_key(:mandatory)
+    end
+
+    it 'incluye :mandatory => true cuando se activa' do
+      request.mandatory = true
+
+      expect(request.amqp_options[:mandatory]).to be(true)
+    end
+  end
+
+  describe 'Publisher Confirms attributes' do
+    it 'tiene mandatory=false y confirm_timeout=nil por defecto' do
+      req = described_class.new('foo')
+
+      expect(req.mandatory).to be(false)
+      expect(req.confirm_timeout).to be_nil
+    end
+
+    it 'permite asignar mandatory y confirm_timeout' do
+      req = described_class.new('foo')
+
+      req.mandatory = true
+      req.confirm_timeout = 0.5
+
+      expect(req.mandatory).to be(true)
+      expect(req.confirm_timeout).to eq(0.5)
+    end
   end
 end