bug_bunny 4.17.0 → 4.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec5013f4d782766d388826265255b008a9c17119b15acef95a05fcb01a9722d5
-  data.tar.gz: 0cd930d1d4c982a0ba9bf73e9562504d0e776c88c760e427dc440a1399b57a13
+  metadata.gz: 030517babaaafccb4ac6b067e1c11ac1cf6d4a6a711919c8455c3dcfe6a79637
+  data.tar.gz: fb9a551e05882e05efc3cd23215773507ae6d5d2baab70681360c04100724d29
 SHA512:
-  metadata.gz: 800c22370b7e39812cc1d90ca74db9ea4736e4354e4061d39a0e0e9d5fbb7fa5ff05c56474f61056a7fe072144339c48d725f040c34c16ba7f0805a314881d66
-  data.tar.gz: 921e0359f5426db49beaf327e67885568313282c3972e9bc2e9d7f88e28fdad032f3258ab73e4cca16f9b3f70cdbf5f42311e3d4f910e4430494ebb4ea8e05a8
+  metadata.gz: a5c4fbaade4883c361a20e705155d2b60dc6b3e6e64905afe34b02a7a7016cd7913bfd9f1f2de09979d357f72b026dbdc3129ad871d128a1b9ee901628a096b6
+  data.tar.gz: fb7b8dd6f7b74dee3c6d13b789dd07ff3abaeda535680a1ab7ea4276269e40a238588403e5fd7c8d2cdb3188acd3b7889d867d4dffed6a19af45d91eefa68591

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## [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`.
+
+### Nuevas funcionalidades
+- Incorporar familia de skills `dev-*` (glosario + comportamiento) y recomponer composites (#47) — @Gabriel
+
+### Correcciones
+- Consistencia README: Quickstart Consumer, `rpc_timeout`, idioma, coexistencia — @Gabriel
+- Escapar `;` en Note del diagrama Mermaid (flujo confirmed) — @Gabriel
+
+### Documentación
+- Marcar verificación humana de `behavior.md` completada (RFC-001 §3.3) — @Gabriel
+- Rework `skill/SKILL.md` a RFC-008 endurecido (dev-compose 2.0.0) — @Gabriel
+- Alinear nota de coexistencia skill/README — @Gabriel
+
+### Otros cambios
+- Migrar de `service-release` a `gem-release` — @Gabriel
+
 ## [4.17.0] - 2026-05-13
 
 ### Nuevas funcionalidades

data/CLAUDE.md

@@ -8,14 +8,30 @@ BugBunny es una gema Ruby que implementa una capa de enrutamiento RESTful sobre
 
 ## Documentación
 
-- **Para humanos**: `docs/` (5 archivos) + `README.md`. Ver README para índice.
-- **Para agentes AI**: `skill/SKILL.md` + `skill/references/`. Es la skill empaquetada que otros proyectos consumen via `skill-manager sync`.
-- **Nunca referenciar `skill/` desde `docs/` o `README.md`** — son audiencias distintas.
+- **Modelo `dev-*` (RFC-001):** artefactos de detalle en `docs/<capa>/`
+  (`data/`, `glossary/`, `behavior/`); compuestos (`README.md` humano,
+  `skill/SKILL.md` agente version-locked) **indexan, no duplican**.
+  Artefactos generados por `dev-structure` / `dev-enrich`; compuestos por
+  `dev-compose`. Verificación humana antes de commitear.
+- **Estado actual:** `docs/data` = n/a (gema sin DB, declarado solo en índice);
+  `docs/glossary` parcial (acreta por PR); `docs/behavior` completo (6 flujos,
+  backfill on-demand); operaciones/interfaz/topología = dev-structure F2 no
+  implementado.
+- **Para agentes AI**: `skill/SKILL.md` (empaquetada en el `.gem`) +
+  `skill/references/`.
+- **Coexistencia transitoria con destino pendiente (RFC-008 §2 — interim de
+  migración):** contrato/arquitectura sigue embebido en
+  `README.md`/`skill/SKILL.md` y las guías how-to viven en `skill/references/`
+  (pre-estándar) porque su capa destino (operaciones/interfaz/topología) es
+  dev-structure F2 no implementado. Por norma: no se fabrica la capa, no se
+  borra el contrato sin destino; migra cuando F2 entregue, mismo PR. Estado
+  transitorio declarado en el índice de artefactos. Origen del gap (resuelto,
+  normado): `sequre/ai_knowledge#95`.
 
 ## Knowledge Base
 - Las skills en `.agents/skills/` incluyen conocimiento de dependencias.
 - Leer la skill de una dependencia ANTES de responder sobre ella.
-- Rebuild: `ruby .agents/skills/skill-manager/scripts/sync.rb`
+- Rebuild: `wispro-agent sync`
 
 ### Entorno
 - Versión de Ruby: leer `.ruby-version`

data/README.md

@@ -58,8 +58,8 @@ module BugBunny
 end
 
 # Worker entrypoint (dedicated thread or process)
-consumer = BugBunny::Consumer.new
-consumer.subscribe(
+BugBunny::Consumer.subscribe(
+  connection:    BugBunny.create_connection,
   queue_name:    'inventory_queue',
   exchange_name: 'inventory',
   routing_key:   'nodes'
@@ -124,7 +124,7 @@ BugBunny.configure do |config|
   config.network_recovery_interval = 5     # seconds, base for exponential backoff
 
   # Timeouts
-  config.rpc_timeout         = 30   # seconds, for synchronous RPC calls
+  config.rpc_timeout         = 10   # seconds (default 10), for synchronous RPC calls
   config.connection_timeout  = 10
   config.read_timeout        = 10
   config.write_timeout       = 10
@@ -339,9 +339,9 @@ BugBunny.consumer_middlewares.use TracingMiddleware
 
 ## Observability
 
-BugBunny implementa de forma nativa las [OpenTelemetry semantic conventions for messaging](https://opentelemetry.io/docs/specs/otel/trace/semantic-conventions/messaging/), inyectando automáticamente campos como `messaging_system`, `messaging_operation`, `messaging_destination_name` y `messaging_message_id` tanto en los headers AMQP como en los log events estructurados.
+BugBunny natively implements the [OpenTelemetry semantic conventions for messaging](https://opentelemetry.io/docs/specs/otel/trace/semantic-conventions/messaging/), automatically injecting fields like `messaging_system`, `messaging_operation`, `messaging_destination_name` and `messaging_message_id` into both the AMQP headers and the structured log events.
 
-Todos los eventos internos se emiten como logs `key=value` compatibles con Datadog, CloudWatch, ELK y ExisRay.
+All internal events are emitted as `key=value` logs compatible with Datadog, CloudWatch, ELK and ExisRay.
 
 ```
 component=bug_bunny event=producer.publish method=POST path=acct/publish messaging_destination_name=acct_x messaging_routing_key=acct.start.42
@@ -353,19 +353,19 @@ component=bug_bunny event=consumer.execution_error error_class=RuntimeError erro
 component=bug_bunny event=consumer.connection_error attempt_count=2 retry_in_s=10 error_message="..."
 ```
 
-### Duraciones medidas internamente
+### Internally measured durations
 
-BugBunny mide y emite duraciones automáticamente — **no es necesario envolver llamadas a `client.publish` con `Process.clock_gettime` en el código de aplicación**. Las unidades siguen las [OpenTelemetry metric semantic conventions](https://opentelemetry.io/docs/specs/semconv/general/metrics/) (`s`, segundos como `Float`).
+BugBunny measures and emits durations automatically — **there is no need to wrap `client.publish` calls with `Process.clock_gettime` in application code**. Units follow the [OpenTelemetry metric semantic conventions](https://opentelemetry.io/docs/specs/semconv/general/metrics/) (`s`, seconds as `Float`).
 
-| Evento | Duración | Mide |
+| Event | Duration | Measures |
 |---|---|---|
-| `producer.published` | `duration_s` | Solo el `basic_publish` (TCP enqueue al broker). |
-| `producer.confirmed` | `publish_duration_s` + `confirm_duration_s` + `duration_s` (total) | Publish + espera de ACK del broker. |
-| `producer.rpc_response_received` | `duration_s` | Round-trip RPC completo (publish + procesamiento remoto + reply). |
-| `consumer.message_processed` | `duration_s` | Procesamiento del mensaje (router + controller + reply). |
-| `consumer.execution_error` | `duration_s` | Tiempo transcurrido hasta el error. |
+| `producer.published` | `duration_s` | Only the `basic_publish` (TCP enqueue to the broker). |
+| `producer.confirmed` | `publish_duration_s` + `confirm_duration_s` + `duration_s` (total) | Publish + wait for broker ACK. |
+| `producer.rpc_response_received` | `duration_s` | Full RPC round-trip (publish + remote processing + reply). |
+| `consumer.message_processed` | `duration_s` | Message processing (router + controller + reply). |
+| `consumer.execution_error` | `duration_s` | Elapsed time until the error. |
 
-Las claves sensibles (`password`, `token`, `secret`, `api_key`, `authorization`, etc.) se filtran automáticamente a `[FILTERED]` en toda la salida de logs.
+Sensitive keys (`password`, `token`, `secret`, `api_key`, `authorization`, etc.) are automatically filtered to `[FILTERED]` across all log output.
 
 ---
 
@@ -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)
@@ -426,17 +426,33 @@ end
 
 ---
 
-## Documentation
-
-- [Concepts](docs/concepts.md) — What BugBunny is, AMQP in 5 minutes, RPC vs fire-and-forget
-- [Routing](docs/howto/routing.md) — Full routing DSL reference
-- [Controllers](docs/howto/controller.md) — Filters, `rescue_from`, `render`, `after_action`
-- [Resource ORM](docs/howto/resource.md) — CRUD, typed and dynamic attributes, `.with` scoping
-- [Client Middleware](docs/howto/middleware_client.md) — Request/response middleware stack
-- [Consumer Middleware](docs/howto/middleware_consumer.md) — Message processing middleware stack
-- [Distributed Tracing](docs/howto/tracing.md) — Propagating trace context through RPC cycles
-- [Rails Setup](docs/howto/rails.md) — Full integration: Puma, Sidekiq, Zeitwerk, health checks
-- [Testing](docs/howto/testing.md) — Unit and integration testing with Bunny mocks
+## Índice de artefactos
+
+Artefactos de detalle (modelo `dev-*`, RFC-001). El README indexa; no duplica.
+
+| Capa | Artefacto | Estado |
+|---|---|---|
+| Datos | — | n/a — gema sin DB (sin schema/models) |
+| Glosario | [docs/glossary/glossary.md](docs/glossary/glossary.md) | parcial, acreta por PR |
+| Comportamiento | [docs/behavior/behavior.md](docs/behavior/behavior.md) | completa — 6 flujos (backfill on-demand) |
+| Operaciones / Interfaz / Topología | — | F2 no implementado (dev-structure) — ver nota |
+
+**Coexistencia transitoria con destino pendiente (RFC-008 §2 — interim de migración):** mientras la capa de detalle destino (operaciones/interfaz/topología) esté declarada pero **no implementada** (dev-structure F1, F2 del plan), permanecen embebidos/cruzados, bajo el interim normado:
+
+- **En este README:** el contrato (jerarquía de excepciones, API de configuración, modos de entrega).
+- **En `skill/SKILL.md`:** además el diagrama de arquitectura (flujo RPC).
+- **Guías how-to** (`skill/references/*.md`, pre-estándar): el README las enlaza pese a la regla "no referenciar `skill/` desde el README" — destino futuro `docs/howto/`.
+
+Por RFC-008 §2: no se fabrica la capa, no se borra contrato sin destino, no se duplica; migra cuando F2 entregue, mismo PR. Estado transitorio declarado, no excepción permanente. Origen del gap (resuelto, normado): [sequre/ai_knowledge#95](https://github.com/sequre/ai_knowledge/issues/95).
+
+How-to (pre-estándar):
+[Routing](skill/references/routing.md) ·
+[Controllers](skill/references/controller.md) ·
+[Resources](skill/references/resource.md) ·
+[Client & Middleware](skill/references/client-middleware.md) ·
+[Consumer](skill/references/consumer.md) ·
+[Errores](skill/references/errores.md) ·
+[Testing](skill/references/testing.md)
 
 ---
 

data/docs/behavior/behavior.md

@@ -0,0 +1,179 @@
+# 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 `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
+
+Flujos de ejecución de la gema. Generado en **modo completo on-demand** (RFC-007 §2 / dev-enrich 1.3.0): backfill solicitado explícitamente, no incremental. Invariante de honestidad (RFC-001 §3.3): anclado a código real (`file:line`), lógica dispersa marcada como tal, cobertura declarada, **verificado por humano 2026-05-18** contra el código (el LLM extrajo las secuencias; humano confirmó).
+
+## Cobertura (OBLIGATORIO)
+
+| Flujo | Estado | Anclaje principal |
+|---|---|---|
+| RPC síncrono | **documentado** | `producer.rb:103-134`, `consumer.rb:152-293` |
+| Fire-and-forget | **documentado** | `producer.rb:47-51,146-161` |
+| Confirmed + basic.return bridge | **documentado** | `producer.rb:72-93,299-333`, `session.rb:204-250` |
+| Consumer subscribe loop + reconnect + health | **documentado** | `consumer.rb:66-127,340-361` |
+| Error handling / RemoteError | **documentado** | `consumer.rb:320-329`, `remote_error.rb`, `raise_error.rb:32-65` |
+| Client middleware stack (onion) | **documentado** | `middleware/stack.rb:43-47`, `base.rb:35-43` |
+
+Cobertura completa a `a5cdb10`. Acreta incremental en cada PR que toque un flujo (default RFC-007). Ausencia futura ≠ inexistencia.
+
+## 2. Cuerpo
+
+### Flujo: RPC síncrono
+Request-response bloqueante; el hilo emisor espera en `Concurrent::IVar` correlacionado por `correlation_id` hasta reply o `RequestTimeout`.
+
+```mermaid
+sequenceDiagram
+    participant CL as Client
+    participant MW as Middleware Stack
+    participant P as Producer
+    participant BR as RabbitMQ
+    participant CO as Consumer
+    participant CT as Controller
+    CL->>MW: request (delivery_mode=:rpc)
+    MW->>P: call (onion → producer.rpc)
+    P->>P: ensure_reply_listener! · cid=UUID · reply_to=amq.rabbitmq.reply-to
+    P->>P: @pending_requests[cid]=IVar
+    P->>BR: publish (type=path, correlation_id, reply_to)
+    P-->>P: future.value(timeout) — BLOQUEA
+    BR->>CO: deliver
+    CO->>CO: consumer middlewares · recognize(method,path)
+    CO->>CT: Controller.call(headers, body)
+    CT->>CT: before/around/after + action → render
+    CT-->>CO: response (o handle_exception → 500)
+    CO->>BR: reply a reply_to (correlation_id)
+    BR->>P: reply (basic_consume listener)
+    P->>P: @pending_requests[cid].set → IVar resuelve
+    P->>P: on_rpc_reply · parse_response
+    P-->>CL: response hidratada
+    Note over P: bloqueo L122 · timeout → RequestTimeout L124
+```
+Contexto: `client.rb:97-101` → `producer.rb:103-134` (bloqueo L122) → reply listener `producer.rb:405-424` → `consumer.rb:247,272-293`.
+
+### Flujo: Fire-and-forget
+Publica y retorna `{ 'status' => 202 }` sin esperar broker ni consumer.
+
+```mermaid
+sequenceDiagram
+    participant CL as Client
+    participant MW as Middleware Stack
+    participant P as Producer
+    participant BR as RabbitMQ
+    CL->>MW: publish (delivery_mode=:publish)
+    MW->>P: call (onion → producer.fire)
+    P->>BR: publish_message (TCP enqueue, sin ACK)
+    P-->>CL: { status: 202, body: nil } (inmediato)
+```
+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.
+
+```mermaid
+sequenceDiagram
+    participant CL as Client
+    participant P as Producer
+    participant S as Session
+    participant BR as RabbitMQ
+    participant RT as Bunny reader thread
+    CL->>P: publish confirmed:true [mandatory]
+    P->>S: register_return_listener(cid) → Event+slot
+    P->>BR: publish_message (mandatory)
+    P-->>P: wait_for_confirms! — BLOQUEA (IVar si hay timeout)
+    BR-->>RT: basic.return (si unroutable)
+    RT->>S: handle_broker_return → signal_return_listener
+    S->>S: slot[:info]=info · slot[:event].set
+    BR-->>P: confirms (ack/nack)
+    P->>P: handle_confirm_result — nack → PublishNacked
+    P->>P: handle_return_result → event.wait(RETURN_RACE_WINDOW_S=0.05s)
+    P->>P: slot[:info] presente → raise_unroutable!
+    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`) · 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.
+
+```mermaid
+sequenceDiagram
+    participant C as Consumer
+    participant S as Session
+    participant BR as RabbitMQ
+    participant H as Health TimerTask
+    C->>S: exchange/queue declare · q.bind(rk)
+    C->>H: start_health_check (touch file)
+    C->>BR: q.subscribe(manual_ack, block:true) — LOOP
+    loop por mensaje
+        BR->>C: deliver → consumer_middlewares → process_message
+    end
+    H-->>S: cada interval: queue_declare(passive:true)
+    H-->>S: falla → cierra session (fuerza reconnect)
+    Note over C: rescue StandardError → attempt++ · backoff min(nri*2^(n-1), max) · sleep · retry (redeclara)
+    Note over C: max_reconnect_attempts alcanzado → raise (fatal) · ensure → shutdown
+```
+Contexto: `consumer.rb:66-127` (retry L106-124), `consumer.rb:340-361` (health). **Honestidad:** health check es thread aparte (TimerTask); no es parte del manejo de error del loop — se acoplan sólo vía cierre de session. Marcado, no fingido como un único flujo.
+
+### Flujo: Error handling / RemoteError
+Excepción no manejada en controller → serializada (clase/mensaje/backtrace[0..25]) → reply 500 → reconstruida client-side por `Middleware::RaiseError`.
+
+```mermaid
+sequenceDiagram
+    participant CT as Controller
+    participant CO as Consumer
+    participant BR as RabbitMQ
+    participant RE as Middleware::RaiseError
+    participant CL as Caller
+    CT->>CT: action raise → rescue → handle_exception
+    CT->>CT: rescue_from match? sí→handler · no→500 + RemoteError.serialize
+    CT-->>CO: response 500 (bug_bunny_exception)
+    CO->>CO: handle_fatal_error → RemoteError.serialize
+    CO->>BR: reply 500 a reply_to
+    BR->>RE: response (vía reply listener + parse_response)
+    RE->>RE: status 500..599 + bug_bunny_exception
+    RE-->>CL: raise BugBunny::RemoteError(class,message,backtrace)
+```
+Contexto: `controller.rb:200-234`, `consumer.rb:320-329`, `remote_error.rb:29-48`, `raise_error.rb:32-65`. **Honestidad:** backtrace truncado a 25 líneas en serialize; si el controller nunca llega a responder, el cliente expira por timeout en vez de recibir el error (no hay path de error garantizado).
+
+### Flujo: Client middleware stack (onion)
+`Stack#build` hace `@middlewares.reverse.inject(final_action)` → el **primer `use` queda como el más externo** (corre `on_request` primero, `on_complete` último). Documentado en `stack.rb:37-39`; sigue la convención Rack/Faraday (primer registrado = capa externa).
+
+```mermaid
+sequenceDiagram
+    participant U as Caller
+    participant O as MW externo (primer use)
+    participant I as MW interno (último use)
+    participant P as Producer (final_action)
+    U->>O: call(env)
+    O->>O: on_request
+    O->>I: @app.call(env)
+    I->>I: on_request
+    I->>P: @app.call(env) → rpc/fire/confirmed
+    P-->>I: response
+    I->>I: on_complete
+    I-->>O: response
+    O->>O: on_complete (RaiseError: 4xx/5xx → raise)
+    O-->>U: response / excepción
+```
+Contexto: `middleware/stack.rb:31-47` (build L43-47, `reverse.inject`), `base.rb:35-43` (`call`: on_request → @app.call → on_complete), `client.rb:160-163` (final_action + `@stack.build(final_action).call(req)`). Orden: `use A; use B` → **A más externo** (corre primero), B envuelve al producer. `RaiseError` solo define `on_complete` (sin `on_request`).
+
+## 3. Inferencias
+
+| Inferencia | confidence | a verificar (humano) |
+|---|---|---|
+| 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
+
+- **Modo:** completo on-demand (RFC-007 §2). Default futuro = incremental por PR; este artefacto se actualiza en el mismo PR que toque cualquier flujo.
+- **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:** 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/glossary/glossary.md

@@ -0,0 +1,148 @@
+# Glosario — bug_bunny
+
+> meta: artefacto `glosario` · RFC-009 (binding opcional, r: §2 materialización no-tabular) · generado dev-enrich (siembra) · anclado a `a5cdb10` · cobertura: parcial, acreta por PR
+
+## 1. Resumen
+
+Vocabulario de dominio (DDD ubiquitous language) del bounded context **bug_bunny**: capa de routing RESTful sobre AMQP. Siembra inicial (dev-enrich: glosario SE PUEDE sembrar = migración desde código + conocimiento). **Gema sin capa de datos** (`docs/data/datos.md` = n/a): por RFC-009 §2 el `Binding:` es **opcional** — se cita solo cuando un símbolo público estable *es* el concepto (clase/value object que lo nombra); concepto o patrón sin símbolo propio → `Binding: n/a`. Nunca binding sintético.
+
+## 2. Cuerpo
+
+## Request
+Value object con toda la metadata del mensaje saliente: path, verbo, body, params, headers y opciones AMQP (exchange, routing_key, delivery_mode, persistent, mandatory).
+
+**Binding:**
+- `lib/bug_bunny/request.rb` — `BugBunny::Request` (la clase *es* el concepto)
+
+## Delivery Mode
+Modo de entrega de un mensaje en este contexto: `:rpc` (síncrono, bloquea esperando reply), `:publish` (fire-and-forget, retorna 202), `:confirmed` (async con ACK del broker).
+
+**Binding:** n/a (modo, no símbolo que sea el concepto; se realiza vía `Client#delivery_mode` / `Producer#{rpc,fire,confirmed}`)
+
+## RPC
+Request-response síncrono sobre la pseudo-cola `amq.rabbitmq.reply-to` (Direct Reply-to). El hilo emisor bloquea en un `Concurrent::IVar` hasta el reply o `RequestTimeout`.
+
+**Binding:** n/a (patrón; sin clase que sea "RPC")
+
+## Fire-and-Forget
+Publicación asíncrona sin espera de respuesta; el caller retorna `{ 'status' => 202 }` de inmediato.
+
+**Binding:** n/a (patrón; sin clase propia)
+
+## Publisher Confirms
+Confirmación del broker (`basic.ack`) de recepción del mensaje, expuesta como `confirmed: true`. Dos señales asíncronas se convierten en excepciones raise-eables en el hilo de publish: `basic.nack` → `PublishNacked`; `basic.return` (mandatory unroutable) → `PublishUnroutable`.
+
+**Binding:** n/a (extensión AMQP; se realiza en `Producer#confirmed`)
+
+## Mandatory
+Flag de `basic.publish` que pide al broker retornar el mensaje (`basic.return`) si no es ruteable a ninguna cola. Inerte sin `confirmed: true`.
+
+**Binding:** n/a (flag AMQP)
+
+## Route
+Patrón compilado verbo+path → Controller#acción; extrae params nombrados por regex.
+
+**Binding:**
+- `lib/bug_bunny/routing/route.rb` — `BugBunny::Routing::Route`
+
+## RouteSet
+Registro central de rutas + DSL (`resources`, `namespace`, `member`, `collection`) y `recognize`.
+
+**Binding:**
+- `lib/bug_bunny/routing/route_set.rb` — `BugBunny::Routing::RouteSet`
+
+## Controller
+Base class tipo Rails que recibe el mensaje deserializado (body+headers) y produce una respuesta HTTP. Soporta `before/around/after_action`, `rescue_from`, `render`.
+
+**Binding:**
+- `lib/bug_bunny/controller.rb` — `BugBunny::Controller`
+
+## Consumer
+Worker bloqueante que escucha una cola, deserializa, rutea via `RouteSet` al controller y responde (RPC reply o ack). Incluye health check periódico.
+
+**Binding:**
+- `lib/bug_bunny/consumer.rb` — `BugBunny::Consumer`
+
+## Producer
+Publicador de bajo nivel: serialización, resolución de opciones AMQP, correlación RPC, sincronización de Publisher Confirms.
+
+**Binding:**
+- `lib/bug_bunny/producer.rb` — `BugBunny::Producer`
+
+## Session
+Wrapper de un canal Bunny con init perezoso, cascada de config (defaults gema → global → request) y resiliencia (double-checked locking, auto-reconnect). Correlaciona `basic.return` cross-thread.
+
+**Binding:**
+- `lib/bug_bunny/session.rb` — `BugBunny::Session`
+
+## Client
+API de alto nivel con arquitectura onion-middleware: construye `Request`, ejecuta el stack y delega en `Producer` via connection pool.
+
+**Binding:**
+- `lib/bug_bunny/client.rb` — `BugBunny::Client`
+
+## Resource
+ORM tipo ActiveModel: declara microservicios remotos como objetos Ruby con CRUD (`find`, `where`, `create`, `save`, `destroy`) que emiten RPC/async. `.with` da override de contexto thread-local.
+
+**Binding:**
+- `lib/bug_bunny/resource.rb` — `BugBunny::Resource`
+
+## Exchange
+Entidad AMQP que rutea mensajes a colas según binding. Declarada con `durable`/`auto_delete` por la cascada de config.
+
+**Binding:** n/a (entidad del broker, no de la gema; se realiza en `Session#exchange`)
+
+## Queue
+Entidad AMQP que retiene mensajes hasta que un Consumer se suscribe. Default de la gema desde 4.16: compartida y durable.
+
+**Binding:** n/a (entidad del broker; se realiza en `Session#queue`)
+
+## Routing Key
+Clave que el exchange usa para matchear mensaje→binding de cola. Por defecto = `path` del request salvo override explícito.
+
+**Binding:** n/a (concepto AMQP; se computa en `Request#final_routing_key`)
+
+## RemoteError
+Error 500 que propaga clase, mensaje y backtrace originales de la excepción del worker remoto al caller RPC.
+
+**Binding:**
+- `lib/bug_bunny/remote_error.rb` — `BugBunny::RemoteError`
+
+## PublishNacked
+Excepción cuando el broker rechaza (`basic.nack`) un mensaje en modo `:confirmed`. Opt-out con `config.nack_raise = false`.
+
+**Binding:**
+- `lib/bug_bunny/exception.rb` — `BugBunny::PublishNacked`
+
+## PublishUnroutable
+Excepción cuando un mensaje `mandatory: true` en `:confirmed` no es ruteable a ninguna cola (`basic.return`). Opt-out con `config.return_raise = false`.
+
+**Binding:**
+- `lib/bug_bunny/exception.rb` — `BugBunny::PublishUnroutable`
+
+## Consumer Middleware
+Cadena transversal que corre antes del dispatch al controller (tracing, auth, logging); recibe `delivery_info`, `properties`, `body`; debe hacer yield.
+
+**Binding:**
+- `lib/bug_bunny/consumer_middleware.rb` — `BugBunny::ConsumerMiddleware`
+
+## Observability
+Mixin de logging estructurado `key=value` que implementa OTel semantic conventions for messaging; `safe_log` nunca lanza; filtra claves sensibles a `[FILTERED]`.
+
+**Binding:**
+- `lib/bug_bunny/observability.rb` — `BugBunny::Observability`
+
+## 3. Inferencias
+
+| Término | Inferencia | confidence | a verificar |
+|---|---|---|---|
+| "bounded context = bug_bunny" | El significado es local a la gema, no global del ecosistema | inferred | humano confirma encuadre DDD |
+| Significado de cada término | Sembrado desde código + glosario ad-hoc migrado del `skill/SKILL.md`; el LLM redactó la prosa | inferred | humano aporta/corrige el significado de negocio (dev-enrich: el LLM infiere menos) |
+| `Binding:` a clase que "es el concepto" | Criterio RFC-009 §2 aplicado por el LLM (qué símbolo *es* el término) | inferred | humano confirma que el símbolo materializa el término y no es sintético |
+
+## 4. Cobertura y fronteras
+
+- **Parcial y acreta:** glosario sembrado (RFC-009 §2; dev-enrich "se PUEDE sembrar"). Términos nuevos se agregan en el PR que los introduce. Ausencia ≠ inexistencia.
+- **Binding opcional (RFC-009 §2, gap gema-sin-datos resuelto, RFC-009 §5 / issue ai_knowledge#91):** sin capa de datos el `Binding:` se omite/`n/a`; se cita símbolo solo cuando *es* el concepto.
+- **Frontera (DAMA-DMBOK):** esto es Business Glossary (term-céntrico). El Data Dictionary (`definición` por columna, RFC-002 §2.c) no aplica — sin tablas.
+- **Frescura:** si un PR renombra/elimina una clase con `Binding:`, el reviewer verifica que ningún binding quede colgado (RFC-009 §2).

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

@@ -7,8 +7,24 @@ module BugBunny
   # Permite capturar cualquier error de la librería con un `rescue BugBunny::Error`.
   class Error < ::StandardError; 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.

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.0'
+  VERSION = '4.18.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

@@ -1,28 +1,86 @@
+---
+name: bug_bunny
+description: >-
+  Routing RESTful sobre AMQP/RabbitMQ para microservicios Ruby/Rails: RPC
+  síncrono, fire-and-forget, Publisher Confirms, Resource ORM, controllers y
+  routing DSL tipo Rails. Usar cuando se integra/depura comunicación entre
+  servicios via RabbitMQ con la gema bug_bunny.
+triggers:
+  - gema `bug_bunny` / módulo `BugBunny`
+  - "símbolos `BugBunny::{Client,Consumer,Resource,Controller}`"
+  - "excepciones `BugBunny::{PublishUnroutable,PublishNacked,RemoteError}`"
+---
+
 # BugBunny Expert
 
-Skill de conocimiento completo sobre BugBunny. Consultame para cualquier pregunta sobre integración, arquitectura, API, errores y antipatrones.
+## Qué es / cuándo usar
 
----
+Gema Ruby: capa de routing RESTful sobre AMQP/RabbitMQ. Microservicios se comunican via RabbitMQ con ergonomía tipo Rails (verbos, controllers, rutas, RPC síncrono, fire-and-forget, Publisher Confirms). Usar esta dependencia cuando integrás/depurás comunicación entre servicios con `bug_bunny`: publicar/consumir, ORM remoto, manejo de errores de broker.
+
+## Contrato resumido (piso mínimo)
+
+> 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**
+
+| Símbolo | Uso típico |
+|---|---|
+| `BugBunny::Client` | `client.request(url, method: :get)` (RPC sync) · `client.publish(url, body:)` (fire-and-forget, 202) · `client.publish(url, confirmed: true, mandatory: true)` (publisher confirms) |
+| `BugBunny::Resource` | ORM tipo AR: `self.exchange=` / `self.resource_name=` / `connection_pool=`; `find/where/create/save/destroy` |
+| `BugBunny::Consumer` | `BugBunny::Consumer.subscribe(connection: BugBunny.create_connection, queue_name:, exchange_name:, routing_key:)` (loop bloqueante) |
+| `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` · `CommunicationError` (envuelve cualquier `Bunny::Exception` — TCP/conn/canal; `.cause` preserva original) |
+
+**Uso típico**
+
+```ruby
+# Servidor
+BugBunny.routes.draw { resources :nodes }
+BugBunny::Consumer.subscribe(connection: BugBunny.create_connection,
+  queue_name: 'inv_q', exchange_name: 'inventory', routing_key: 'nodes')
+
+# Cliente
+client = BugBunny::Client.new(pool: pool)
+client.request('nodes/42', method: :get)        # => { 'status' => 200, 'body' => {...} }
+client.publish('events', body: { type: 'x' })   # => { 'status' => 202 }
+```
+
+**Gotchas/breaking críticos**
+
+- URL es **posicional**, no kwarg `path:` — `client.publish(**args)` con `path:` → `ArgumentError`.
+- `confirmed: true` ≠ persistente: para sobrevivir restart hace falta `persistent: true` (+ queue `durable`).
+- `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)
+
+El detalle vive en `docs/<capa>/` (modelo `dev-*`); esta skill **indexa y resume**, no duplica. Links relativos = version-locked (mismo tag del release; `gemspec.files` incluye `docs/**`).
+
+| Capa | Artefacto | Estado |
+|---|---|---|
+| Glosario de dominio | [docs/glossary/glossary.md](../docs/glossary/glossary.md) | parcial, acreta por PR |
+| Comportamiento (flujos) | [docs/behavior/behavior.md](../docs/behavior/behavior.md) | completa — 6 flujos |
+| Datos | — | n/a — gema sin DB |
+| Operaciones / Interfaz / Topología | — | F2 no implementado — ver Cobertura y fronteras |
+
+> **Glosario:** migrado a [docs/glossary/glossary.md](../docs/glossary/glossary.md)
+> (RFC-008 §2 — el compuesto referencia, no copia). Términos AMQP base
+> (Exchange, Queue, Routing Key, RPC, Publisher Confirms, Mandatory, etc.) y su
+> binding físico están ahí.
+
+## Cobertura y fronteras
+
+**Coexistencia transitoria con destino pendiente (RFC-008 §2 — interim de migración):** mientras la capa de detalle destino (operaciones/interfaz/topología) esté declarada pero **no implementada** (dev-structure F1, F2 del plan), permanecen embebidos bajo el interim normado:
+
+- **En esta skill (abajo):** el contrato detallado (jerarquía de excepciones, API de config, modos de entrega) **y** el diagrama de arquitectura (flujo RPC). El *Contrato resumido* de arriba es el piso mínimo (RFC-008 §2); lo de abajo es el detalle interim hasta que exista `docs/api|interface|topology`.
+- **En `README.md`:** el contrato (sin el diagrama de arquitectura).
+- **Guías how-to** (`references/*.md`, pre-estándar): destino futuro `docs/howto/`.
 
-## Glosario
-
-**AMQP** — Advanced Message Queuing Protocol. Protocolo binario que implementa RabbitMQ.
-**Bunny** — Cliente Ruby para AMQP. BugBunny lo usa internamente para conexiones, canales y publicación.
-**Exchange** — Recibe mensajes del producer y los enruta a queues según reglas. Tipos: `direct` (match exacto), `topic` (wildcards), `fanout` (broadcast).
-**Queue** — Almacena mensajes hasta que un consumer los consume. Las queues durables sobreviven reinicios del broker.
-**Routing Key** — String que el producer adjunta al mensaje. El exchange lo usa para decidir a qué queues enrutar.
-**Binding** — Enlace entre un exchange y una queue, opcionalmente con un patrón de routing key.
-**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`. Dos señales asíncronas del broker, ambas convertidas en excepciones raise-eables en el publish thread:
-- **NACK** (rechazo explícito) → `BugBunny::PublishNacked` (configurable via `config.nack_raise = false`).
-- **basic.return** (mandatory unroutable) → `BugBunny::PublishUnroutable` (configurable via `config.return_raise = false`).
-**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`.
+Por RFC-008 §2: no se fabrica la capa, no se borra contrato sin destino, no se duplica; migra cuando F2 entregue, mismo PR. Estado transitorio declarado, no excepción permanente. Origen del gap (resuelto, normado): [sequre/ai_knowledge#95](https://github.com/sequre/ai_knowledge/issues/95).
 
 ---
 
@@ -374,8 +432,8 @@ 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.
 
 Ver catálogo completo en [Errores](references/errores.md).
 

data/skills.yml

@@ -8,7 +8,17 @@ skills:
     repo: sequre/ai_knowledge
   gem-release:
     repo: sequre/ai_knowledge
-  skill-builder:
+  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
+  dev-flow:
     repo: sequre/ai_knowledge
   matrix-element:
     repo: sequre/ai_knowledge
@@ -17,10 +27,6 @@ skills:
       auth_token: "${MATRIX_AUTH_TOKEN}"
       rooms:
         agents: "!VCHwQXgmXdyhhhPhoz:matrix.cloud.wispro.co"
-  skill-feedback:
-    repo: sequre/ai_knowledge
-  agent-issue:
-    repo: sequre/ai_knowledge
   documentation-writer:
     repo: github/awesome-copilot
     path: skills/documentation-writer

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')
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bug_bunny
 version: !ruby/object:Gem::Version
-  version: 4.17.0
+  version: 4.18.0
 platform: ruby
 authors:
 - gabix
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-13 00:00:00.000000000 Z
+date: 2026-05-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny
@@ -233,6 +233,8 @@ files:
 - CLAUDE.md
 - README.md
 - Rakefile
+- docs/behavior/behavior.md
+- docs/glossary/glossary.md
 - initializer_example.rb
 - lib/bug_bunny.rb
 - lib/bug_bunny/client.rb
@@ -281,6 +283,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
@@ -304,7 +307,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.0/skill
+  documentation_uri: https://github.com/gedera/bug_bunny/blob/v4.18.0/skill
 post_install_message:
 rdoc_options: []
 require_paths: