bug_bunny 4.17.0 → 4.17.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec5013f4d782766d388826265255b008a9c17119b15acef95a05fcb01a9722d5
-  data.tar.gz: 0cd930d1d4c982a0ba9bf73e9562504d0e776c88c760e427dc440a1399b57a13
+  metadata.gz: 50bb70f17d783b52abeb208bc362953c9494b61853f836da84f73552e3a76966
+  data.tar.gz: 37f9550b64942b1e544a6e7d593c1695f1293c6a1b488e1b0bec3179d1f3b7a4
 SHA512:
-  metadata.gz: 800c22370b7e39812cc1d90ca74db9ea4736e4354e4061d39a0e0e9d5fbb7fa5ff05c56474f61056a7fe072144339c48d725f040c34c16ba7f0805a314881d66
-  data.tar.gz: 921e0359f5426db49beaf327e67885568313282c3972e9bc2e9d7f88e28fdad032f3258ab73e4cca16f9b3f70cdbf5f42311e3d4f910e4430494ebb4ea8e05a8
+  metadata.gz: 4733c50dcb6824c4e7d53bc0842e823b0674c13bf6cd9d963f99b6fa090166d083ca64cc6e65eba2fc29bff09be840772a6404fae19e62f3dd9b6dbcf56fc2d3
+  data.tar.gz: e9613f65b4bce0ad19aa8c19f259c6a3069ba4dfe185e4146a5992ddfbd20b3428816ed882e9d637f2b4a85d1d5d307094763bf8f3082900e8c6d9d3fe8a1fb7

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # 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

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.
 
 ---
 
@@ -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,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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BugBunny
-  VERSION = '4.17.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/**`).
+
+| 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).
 
 ---
 

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bug_bunny
 version: !ruby/object:Gem::Version
-  version: 4.17.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.17.0/skill
+  documentation_uri: https://github.com/gedera/bug_bunny/blob/v4.17.1/skill
 post_install_message:
 rdoc_options: []
 require_paths: