bug_bunny 4.16.0 → 4.17.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67e58763b6f088c44e17121922ecb618c9ccef8738096d534c578eea021c5f94
-  data.tar.gz: 47fe7485dd056e9ffb8a7e5268b97e4d0173e0441984506b5528f5c43643da7a
+  metadata.gz: 50bb70f17d783b52abeb208bc362953c9494b61853f836da84f73552e3a76966
+  data.tar.gz: 37f9550b64942b1e544a6e7d593c1695f1293c6a1b488e1b0bec3179d1f3b7a4
 SHA512:
-  metadata.gz: f0a5927c4a4a450b414ee38ffbc25a0a97a80b2678d32a19d524a51367572f7b5e2935e29a81bf9afbdd2cfb0b634e9b60a322b828ff14ba0f79e60982148723
-  data.tar.gz: e66726447226ceb96f2d3b81dd759209fd8e54e7ea67bb85870cc805e44747e81f8121a821fd7a6fa65435ae3ba95e3cd62631ef0687fa0543f29848e21f4682
+  metadata.gz: 4733c50dcb6824c4e7d53bc0842e823b0674c13bf6cd9d963f99b6fa090166d083ca64cc6e65eba2fc29bff09be840772a6404fae19e62f3dd9b6dbcf56fc2d3
+  data.tar.gz: e9613f65b4bce0ad19aa8c19f259c6a3069ba4dfe185e4146a5992ddfbd20b3428816ed882e9d637f2b4a85d1d5d307094763bf8f3082900e8c6d9d3fe8a1fb7

data/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## [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
+- **`Client::REQUEST_ATTRS` extendido con metadata AMQP estándar (#45):** Los siguientes atributos del Request ahora pueden pasarse como kwargs directos en `client.publish` / `client.request` sin necesidad del block API:
+  - `persistent` (Boolean) — `delivery_mode: 2` AMQP. Critical: por default es `false`; `confirmed: true` **NO** lo implica.
+  - `correlation_id` (String) — Tracing explícito (sobreescribe el auto-asignado por RPC y `return_raise`).
+  - `priority` (Integer 0-255).
+  - `app_id` (String).
+  - `content_type` (String, default `'application/json'`).
+  - `content_encoding` (String).
+  - `expiration` (String, TTL en ms).
+
+  ```ruby
+  # Antes (4.16): requería block API
+  client.publish('evt', exchange: 'x', confirmed: true) do |req|
+    req.persistent = true
+    req.correlation_id = 'cid-123'
+  end
+
+  # Ahora (4.17): kwargs directos
+  client.publish('evt', exchange: 'x', confirmed: true,
+                 persistent: true, correlation_id: 'cid-123')
+  ```
+
+  El block API sigue funcionando para overrides puntuales o para atributos no expuestos (`timestamp`, `type`, `reply_to`).
+
+### Correcciones
+- **`apply_args` usa `args.key?` en lugar de truthy check:** Permite pasar valores falsy explícitos (ej. `persistent: false`, `priority: 0`) que antes se filtraban silenciosamente como si no se hubieran pasado.
+
+### Documentación (motivado por #45 — adopción real en sequre/box_radius_manager#18)
+- README + SKILL.md cubren cuatro gotchas detectados solo en integration tests:
+  1. `url` es positional, no kwarg `:path`. Splatear un hash con `path:` rompe.
+  2. `confirmed: true` no implica `persistent: true` — son flags ortogonales.
+  3. Default `exchange_options` es `{ durable: false }` — publishers a exchange compartido deben pasar `exchange_options: { durable: true }` explícito.
+  4. `instance_double` no detecta arity mismatch con splat de kwargs — recomendación de smoke test integration para cada publisher nuevo.
+- Nueva sección "Production publisher recipe" en README y receta canónica en SKILL.md con la combinación recomendada para auditoría/billing/accounting.
+- `skill/references/client-middleware.md` con tabla completa de kwargs de Request actualizada.
+
 ## [4.16.0] - 2026-05-13
 
 ### Cambios de comportamiento (semi-breaking)

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
@@ -210,6 +210,73 @@ client.publish('events', body: { type: 'user.signed_in', user_id: 42 })
 client.request('users', method: :get, params: { role: 'admin', page: 2 })
 ```
 
+### Gotchas
+
+**URL is positional, not a kwarg.** The first argument of `client.request` / `client.publish` is positional. There is **no** `path:` kwarg, splatting a hash with `path:` will fail silently or raise `ArgumentError`:
+
+```ruby
+args = { exchange: 'ingest.x', body: payload }
+client.publish(**args)              # ❌ ArgumentError: wrong number of arguments
+client.publish('event.name', **args) # ✅
+```
+
+**Block runs after kwargs.** Keyword args are applied first; the block (if given) can override them. Use kwargs for the common case and block for atypical setup:
+
+```ruby
+client.publish('evt', exchange: 'x', persistent: true) do |req|
+  req.timestamp = some_past_time   # only via block — not in REQUEST_ATTRS
+end
+```
+
+### Production publisher recipe
+
+Defaults aimed at sane microservices — declare durable exchanges, persistent messages, confirmed delivery with mandatory routing, explicit correlation id:
+
+```ruby
+client.publish('acct.start',
+               exchange:         'ingest.radius',
+               exchange_type:    :topic,
+               exchange_options: { durable: true },   # match consumer-declared exchange
+               body:             payload,
+               confirmed:        true,
+               mandatory:        true,                # raise PublishUnroutable if no binding
+               persistent:       true,                # delivery_mode: 2 — survives broker restart
+               correlation_id:   SecureRandom.uuid,
+               app_id:           'radius_manager')
+```
+
+| AMQP property | Kwarg | Reason it matters for critical publishers |
+|---|---|---|
+| `delivery_mode` | `persistent: true` | Without it, the message lives only in broker RAM (lost on restart). Default `false`. |
+| `confirmation` | `confirmed: true` | Block until the broker acks. Without it, `client.publish` returns 202 before the broker sees the message. |
+| `mandatory` | `mandatory: true` | Catches misrouted publishes. Combined with `return_raise` (default `true`), raises `PublishUnroutable` instead of silently dropping. |
+| `exchange durable` | `exchange_options: { durable: true }` | Match the exchange definition that consumers declare. Mismatch raises `Bunny::PreconditionFailed`. |
+| `correlation_id` | `correlation_id:` | Tracing. Auto-generated when missing for RPC and for `confirmed + mandatory + return_raise`, but explicit is preferred. |
+
+### Testing publishers
+
+Mocks of `Client` (via `instance_double`) **do not catch arity mismatches** when the caller does splat (`**args`). Signature errors like passing `path:` as kwarg or unknown keys won't surface in unit tests with mocks. **Add a smoke integration test** for new publishers — declare an exclusive queue, bind to the exchange, publish, `queue.pop`, assert `correlation_id`, `headers`, `routing_key`, `delivery_mode`:
+
+```ruby
+RSpec.describe 'MyPublisher', :integration do
+  it 'publishes with correct AMQP metadata' do
+    conn = BugBunny.create_connection
+    ch   = conn.create_channel
+    x    = ch.topic('ingest.radius', durable: true)
+    q    = ch.queue('', exclusive: true).bind(x, routing_key: 'acct.#')
+
+    MyPublisher.call(payload)
+
+    _delivery, props, body = q.pop(manual_ack: false)
+    expect(props.correlation_id).not_to be_nil
+    expect(props.delivery_mode).to eq(2)         # persistent
+    expect(JSON.parse(body)).to include(...)
+  ensure
+    conn&.close
+  end
+end
+```
+
 ### Publisher Confirms (delivery-critical events)
 
 For events where you need a delivery guarantee from the broker (auditing, billing, accounting) without the cost of a full RPC, use `publish` with `confirmed: true`. The call blocks until the broker acknowledges receipt:
@@ -272,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
@@ -286,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.
 
 ---
 
@@ -359,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,176 @@
+# Comportamiento — bug_bunny
+
+> meta: artefacto `comportamiento` · RFC-007 (cadencia incremental default / completo on-demand) · generado dev-enrich 1.3.0 (backfill on-demand) · anclado a `a5cdb10` · cobertura: completa (6 flujos) · verificado por humano 2026-05-18
+
+## 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`.
+
+### 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`).
+
+### 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` |
+
+## 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:** completada 2026-05-18 (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

@@ -29,9 +29,17 @@ module BugBunny
     attr_accessor :delivery_mode
 
     # Argumentos del cliente que se mapean 1:1 a setters del Request.
+    #
+    # Incluye opciones de enrutamiento (`delivery_mode`, `method`, `body`, `exchange`,
+    # `exchange_type`, `routing_key`, `timeout`, `params`), de infraestructura
+    # (`exchange_options`, `queue_options`) y de metadata AMQP estándar
+    # (`persistent`, `correlation_id`, `priority`, `app_id`, `content_type`,
+    # `content_encoding`, `expiration`). Lo que no esté acá debe setearse via
+    # block API (`do |req| ... end`).
     REQUEST_ATTRS = %i[
       delivery_mode method body exchange exchange_type routing_key
       timeout exchange_options queue_options params
+      persistent correlation_id priority app_id content_type content_encoding expiration
     ].freeze
 
     # Inicializa un nuevo cliente.
@@ -64,7 +72,8 @@ module BugBunny
     #
     # Envía un mensaje y bloquea la ejecución del hilo actual hasta recibir respuesta.
     #
-    # @param url [String] La ruta del recurso (ej: 'users/1').
+    # @param url [String] La ruta del recurso (ej: 'users/1'). **Argumento posicional** —
+    #   no existe el kwarg `:path`. Splatear un hash con `path:` falla silencioso.
     # @param args [Hash] Opciones de configuración.
     # @option args [Symbol] :method El verbo HTTP (:get, :post, :put, :delete). Default: :get.
     # @option args [Object] :body El cuerpo del mensaje.
@@ -72,7 +81,18 @@ module BugBunny
     # @option args [Integer] :timeout Tiempo máximo de espera.
     # @option args [Hash] :exchange_options Opciones específicas para la declaración del Exchange.
     # @option args [Hash] :queue_options Opciones específicas para la declaración de la Cola.
-    # @yield [req] Bloque para configurar el objeto Request directamente.
+    # @option args [Boolean] :persistent Si `true`, `delivery_mode: 2` (mensaje persiste en disco
+    #   del broker). Default `false`. Útil para mensajes críticos sobre queues durables.
+    # @option args [String] :correlation_id ID de correlación AMQP. Útil para tracing custom.
+    #   Si no se setea, `Producer#rpc` y `Producer#confirmed` (con return_raise) auto-asignan UUID.
+    # @option args [Integer] :priority Prioridad del mensaje (0-255). Requiere queue declarada con
+    #   `x-max-priority` para que el broker la respete.
+    # @option args [String] :app_id Identificador del publisher.
+    # @option args [String] :content_type MIME type. Default `'application/json'`.
+    # @option args [String] :content_encoding Encoding del payload (ej: 'gzip').
+    # @option args [String] :expiration TTL del mensaje en ms (formato AMQP).
+    # @yield [req] Bloque para configurar el objeto Request directamente. Necesario para
+    #   atributos no mapeados como kwarg (ej: `req.timestamp = ...`).
     # @return [Hash] La respuesta del servidor.
     def request(url, **args)
       send(url, **args) do |req|
@@ -87,7 +107,8 @@ module BugBunny
     # que el broker confirme la recepción del mensaje. Útil para eventos críticos (auditoría,
     # billing) donde se requiere garantía de entrega sin el overhead de un RPC completo.
     #
-    # @param url [String] La ruta del evento/recurso.
+    # @param url [String] La ruta del evento/recurso. **Argumento posicional** — no
+    #   existe el kwarg `:path`. Splatear un hash con `path:` falla silencioso.
     # @param args [Hash] Mismas opciones que {#request}, excepto `:timeout`. Adicionales:
     # @option args [Boolean] :confirmed Si `true`, espera `wait_for_confirms` del broker.
     # @option args [Boolean] :mandatory Si `true`, el broker retorna el mensaje si no es ruteable.
@@ -158,12 +179,16 @@ module BugBunny
 
     # Mapea los argumentos generales (no específicos de Publisher Confirms) sobre el Request.
     #
+    # Usa `args.key?` en lugar de truthy check para que `persistent: false`,
+    # `priority: 0` u otros valores falsy explícitos del caller sean honrados
+    # (no se filtran como si no hubieran sido pasados).
+    #
     # @param req [BugBunny::Request]
     # @param args [Hash]
     # @return [void]
     def apply_args(req, args)
       REQUEST_ATTRS.each do |key|
-        req.public_send("#{key}=", args[key]) if args[key]
+        req.public_send("#{key}=", args[key]) if args.key?(key)
       end
       req.headers.merge!(args[:headers]) if args[:headers]
     end

data/lib/bug_bunny/version.rb

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

data/skill/SKILL.md

@@ -1,28 +1,85 @@
+---
+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.17.0**. Suficiente para el uso típico sin abrir el detalle; el detalle version-locked está en [`../docs/behavior/behavior.md`](../docs/behavior/behavior.md) (6 flujos) y [`../docs/glossary/glossary.md`](../docs/glossary/glossary.md) (símbolos→significado). Antipatrones/API completa: más abajo (embebido interim, ver Cobertura y fronteras).
+
+**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` |
+
+**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`.
+
+## Í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/**`).
 
-## 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`.
+| 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/`.
+
+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).
 
 ---
 
@@ -245,6 +302,21 @@ client.publish('acct.start', exchange: 'acct_x', body: payload,
 # → { 'status' => 202, 'body' => nil }   # broker ACK confirmado
 ```
 
+**Receta canónica de publisher productivo (auditoría / billing / accounting):**
+```ruby
+client.publish('acct.start',
+               exchange:         'ingest.radius',
+               exchange_type:    :topic,
+               exchange_options: { durable: true },    # matchear declaración del consumer
+               body:             payload,
+               confirmed:        true,                 # broker ACK síncrono
+               mandatory:        true,                 # raise PublishUnroutable si no hay binding
+               persistent:       true,                 # delivery_mode: 2 — sobrevive restart
+               correlation_id:   SecureRandom.uuid,    # tracing explícito
+               app_id:           'radius_manager')
+```
+A partir de 4.17, `persistent`, `correlation_id`, `priority`, `app_id`, `content_type`, `content_encoding` y `expiration` están en `Client::REQUEST_ATTRS` y se aceptan como kwargs. El block API sigue funcionando para overrides puntuales o para atributos no expuestos (`timestamp`, `type`).
+
 **Dos señales del broker, dos excepciones simétricas:**
 
 | Señal | Default | Excepción | Campos |
@@ -311,6 +383,29 @@ No guardar el resultado de `Order.with(...)` en una variable para múltiples lla
 ### Registrar middleware durante call()
 No registrar consumer middlewares durante la ejecución de `call()`. El stack toma un snapshot al inicio; los registros concurrentes no afectan la ejecución actual.
 
+### Pasar `path:` como kwarg a `Client#publish` / `#request`
+El primer argumento es **posicional** (`url`). No hay kwarg `:path`. Splatear un hash que tenga `path:` falla con `ArgumentError: wrong number of arguments`. Construir args sin path y pasar la URL aparte:
+```ruby
+args = { exchange: 'x', body: payload }
+client.publish('event.name', **args)   # ✅
+client.publish(**args.merge(path: 'event.name'))  # ❌
+```
+
+### Asumir que `confirmed: true` implica persistencia
+`confirmed: true` solo activa Publisher Confirms (broker ACK síncrono). **NO** setea `delivery_mode: 2`. El default de `Request#persistent` es `false` — el mensaje vive en RAM del broker y se pierde si reinicia. Para eventos críticos sobre queue durable hay que pasar `persistent: true` (a partir de 4.17) o setearlo via block. Tabla de decisión:
+
+| Necesitás | Pasar |
+|---|---|
+| Broker confirma recepción | `confirmed: true` |
+| Mensaje sobrevive restart | `persistent: true` (requiere queue `durable: true`) |
+| Raise si no rutea | `mandatory: true` (+ `return_raise: true` default) |
+
+### Olvidar `exchange_options: { durable: true }` en publishers a exchange compartido
+`DEFAULT_EXCHANGE_OPTIONS = { durable: false, auto_delete: false }`. Si un consumer previamente declaró el exchange como durable (caso normal en producción), un publisher que use el default va a recibir `Bunny::PreconditionFailed - inequivalent arg 'durable'` al re-declarar. Solución: pasar `exchange_options: { durable: true }` en el publisher, o setear global `BugBunny.configure { |c| c.exchange_options = { durable: true } }`.
+
+### Confiar en `instance_double(BugBunny::Client)` para detectar errores de signature
+Limitación de RSpec: `instance_double` valida que el método exista pero **no** valida arity estricta cuando el caller hace `**args` splat. Tests con mocks pasan, integration con broker real rompe. Mitigación: para cada publisher nuevo, sumar un smoke spec `:integration` que declare queue exclusiva con binding, publique, haga `queue.pop`, y verifique `correlation_id`, `delivery_mode`, `headers`, `routing_key`.
+
 ---
 
 ## Errores Comunes

data/skill/references/client-middleware.md

@@ -47,6 +47,18 @@ end
 | `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. |
+| `return_raise` | Boolean | `nil` | Override per-request de `config.return_raise`. Requiere `confirmed: true` y `mandatory: true`. |
+| `persistent` | Boolean | `false` | `delivery_mode: 2` AMQP. Mensaje sobrevive restart del broker. Requiere queue durable. |
+| `correlation_id` | String | nil | ID de correlación AMQP. Auto-asignado UUID en RPC y en `confirmed + mandatory + return_raise`. |
+| `priority` | Integer | nil | Prioridad 0-255. Requiere queue con `x-max-priority`. |
+| `app_id` | String | nil | Identificador del publisher (AMQP `app-id`). |
+| `content_type` | String | `'application/json'` | MIME type del payload. |
+| `content_encoding` | String | nil | Encoding del payload (`'gzip'`, `'deflate'`, etc.). |
+| `expiration` | String | nil | TTL del mensaje en ms (formato AMQP). |
+
+**Gotcha:** el primer argumento de `Client#publish` / `#request` es **posicional** (`url`). No existe el kwarg `:path`. Splatear un hash con `path:` falla con `ArgumentError` o se ignora silencioso.
+
+**Atributos no expuestos como kwarg** (solo via block API): `timestamp` (default `Time.now.to_i`), `type` (default `full_path`), `reply_to` (RPC interno).
 
 ## Producer (bajo nivel)
 

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/client_session_pool_spec.rb

@@ -287,6 +287,108 @@ RSpec.describe BugBunny::Client, 'session pooling' do
     end
   end
 
+  describe 'AMQP metadata kwargs (REQUEST_ATTRS extension)' do
+    let(:fake_exchange) { double('exchange', publish: nil) }
+
+    def stub_producer_capture
+      captured = nil
+      allow_any_instance_of(BugBunny::Producer).to receive(:fire) do |_prod, req|
+        captured = req
+        { 'status' => 202, 'body' => nil }
+      end
+      allow_any_instance_of(BugBunny::Producer).to receive(:confirmed) do |_prod, req|
+        captured = req
+        { 'status' => 202, 'body' => nil }
+      end
+      [-> { captured }]
+    end
+
+    it 'persistent: true se propaga al Request via kwarg' do
+      client = described_class.new(pool: fake_pool(fake_conn))
+      get_req, = stub_producer_capture
+
+      client.publish('evt', exchange: 'x', exchange_type: 'direct', persistent: true)
+
+      expect(get_req.call.persistent).to be(true)
+    end
+
+    it 'persistent: false explícito se honra (no se filtra como falsy)' do
+      client = described_class.new(pool: fake_pool(fake_conn))
+      get_req, = stub_producer_capture
+
+      client.publish('evt', exchange: 'x', exchange_type: 'direct', persistent: false)
+
+      expect(get_req.call.persistent).to be(false)
+    end
+
+    it 'correlation_id: se propaga al Request via kwarg' do
+      client = described_class.new(pool: fake_pool(fake_conn))
+      get_req, = stub_producer_capture
+
+      client.publish('evt', exchange: 'x', exchange_type: 'direct', correlation_id: 'cid-123')
+
+      expect(get_req.call.correlation_id).to eq('cid-123')
+    end
+
+    it 'priority: se propaga al Request via kwarg' do
+      client = described_class.new(pool: fake_pool(fake_conn))
+      get_req, = stub_producer_capture
+
+      client.publish('evt', exchange: 'x', exchange_type: 'direct', priority: 9)
+
+      expect(get_req.call.priority).to eq(9)
+    end
+
+    it 'app_id, content_type, content_encoding, expiration se propagan via kwargs' do
+      client = described_class.new(pool: fake_pool(fake_conn))
+      get_req, = stub_producer_capture
+
+      client.publish('evt',
+                     exchange: 'x', exchange_type: 'direct',
+                     app_id: 'radius_manager',
+                     content_type: 'application/x-protobuf',
+                     content_encoding: 'gzip',
+                     expiration: '60000')
+
+      req = get_req.call
+      expect(req.app_id).to eq('radius_manager')
+      expect(req.content_type).to eq('application/x-protobuf')
+      expect(req.content_encoding).to eq('gzip')
+      expect(req.expiration).to eq('60000')
+    end
+
+    it 'block API sigue funcionando para atributos no expuestos como kwarg (ej: timestamp, type)' do
+      client = described_class.new(pool: fake_pool(fake_conn))
+      get_req, = stub_producer_capture
+
+      ts = Time.now.to_i - 100
+      client.publish('evt', exchange: 'x', exchange_type: 'direct') do |req|
+        req.timestamp = ts
+        req.type = 'custom.type'
+      end
+
+      req = get_req.call
+      expect(req.timestamp).to eq(ts)
+      expect(req.type).to eq('custom.type')
+    end
+
+    it 'kwargs y block API coexisten — block corre después y puede sobrescribir' do
+      client = described_class.new(pool: fake_pool(fake_conn))
+      get_req, = stub_producer_capture
+
+      client.publish('evt',
+                     exchange: 'x', exchange_type: 'direct',
+                     persistent: false, priority: 1) do |req|
+        req.persistent = true
+        req.priority = 9
+      end
+
+      req = get_req.call
+      expect(req.persistent).to be(true)
+      expect(req.priority).to eq(9)
+    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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bug_bunny
 version: !ruby/object:Gem::Version
-  version: 4.16.0
+  version: 4.17.1
 platform: ruby
 authors:
 - gabix
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-13 00:00:00.000000000 Z
+date: 2026-05-19 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
@@ -304,7 +306,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.16.0/skill
+  documentation_uri: https://github.com/gedera/bug_bunny/blob/v4.17.1/skill
 post_install_message:
 rdoc_options: []
 require_paths: