docker-swarm 0.6.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 916ac2da8a8d322e7cbf83d2e9b05d8aa62bd9a4e78c4d31eaef8086811e3e20
-  data.tar.gz: b1328677dfd900829f21faaf112097833c98594f1c713ddd0c9138a352027f47
+  metadata.gz: c4fccd3ff16c561cf1f8563cf2dd518c69fd1a7fc46e9d74b7da804244dd1c4d
+  data.tar.gz: c71beba1337b83edde6eb18f424954e2563c35172e195615ed86b2b40153abe5
 SHA512:
-  metadata.gz: 5b8bb4bdb2d18c0c6a13d8a3e13662afc529c2f8912ad9b858bf52360e91be4ad40ed123ee4aa3db9549eace28ad5a56cbdc9a0207747903491fa35b5abf93db
-  data.tar.gz: 5ec96be7621f4797e55e1de283d2a646ecb8b405984c97a4aca85084dd0f20098771407d6dc2083b03378bff62ee86a33b46f30f56018f2355e06a0f3da7f33d
+  metadata.gz: 9165d28e2a0def50e674578600642dbaf3aca92b586bb5697590828a3081476139013922f45471dd84d45c376b997bd74bf78e3064d12ab14e3fd9bd046d2743
+  data.tar.gz: c2deb17e70f07a51b8e29ac69b9923706e8a57124fd3ddb4d36a30dded13de1fa4024d1a8c9dc1470cb984dd24da5a2a04cb7c6601a4022bcdecb84557516b79

data/CHANGELOG.md

@@ -0,0 +1,126 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.7.1] — 2026-05-29
+
+### Correcciones
+- `Updatable#update`: captura `Version.Index` **antes** de `assign_attributes` para evitar que un payload con versión desactualizada pise el índice real del nodo y provoque `update out of sequence` en Docker — @Pablo
+
+## [0.7.0] — 2026-05-21
+
+### Breaking changes
+- `Connection#request`: retries automáticos sólo en métodos seguros (GET/HEAD/PUT/DELETE/OPTIONS). POST/PATCH ya **no** reintentan para evitar recursos duplicados ante caída de socket — @Gabriel
+- `Base#assign_attributes`: rama muerta que aceptaba no-Hash ahora levanta `ArgumentError` con mensaje claro — @Gabriel
+- Ruby floor: `>= 3.2.0` (antes `>= 2.7.0`), alineado con `activesupport` 8.1 — @Gabriel
+
+### Correcciones
+- `Connection#request`: clasificación de errores por `is_a?(DockerSwarm::Error)` en vez de `class.name.include?`, evita falsos positivos con clases externas — @Gabriel
+- `LogHelper::SENSITIVE_KEYS`: `data` ahora se matchea con `\b` para no filtrar `metadata`, `database` u otras claves legítimas — @Gabriel
+
+### Documentación
+- Re-estructura completa bajo skills `dev-*` (RFC-001/007/008/009/010): nuevos `docs/glossary/glossary.md` (20 términos) y `docs/behavior/behavior.md` (8 flujos load-bearing con Mermaid). `README.md` minimal-control y `skill/SKILL.md` con frontmatter, contrato resumido, version-lock — @Gabriel
+- Eliminados docs ad-hoc pre-estándar (`docs/{api,configuration,errors,models,testing}.md` y `skill/references/`) — @Gabriel
+
+### Mejoras internas
+- CI: tests unitarios en `bundle exec rspec --tag ~type:integration` para que el build verde sea significativo sin Docker disponible — @Gabriel
+- Gemspec: `metadata` con `changelog_uri`/`bug_tracker_uri`/`documentation_uri`/`rubygems_mfa_required` version-locked; `LICENSE`, `CHANGELOG.md` y `docs/**/*` incluidos en `spec.files` para que viajen con el release — @Gabriel
+- `LICENSE` (MIT) agregado al repo — @Gabriel
+- Removido `debug_docker.rb` del repo (artefacto de desarrollo) — @Gabriel
+
+## [0.6.0] - 2026-04-08
+
+### Nuevas funcionalidades
+- `Service#restart`: reinicia un servicio incrementando `ForceUpdate` en el `TaskTemplate`, equivalente a `docker service update --force` — @Gabriel
+
+## [0.5.4] - 2026-04-07
+
+### Correcciones
+- `Inspectable`: todos los atributos deben usar `send(:attr)` para invocar métodos dinámicos — @Gabriel
+
+## [0.5.3] - 2026-04-07
+
+### Mejoras internas
+- `Inspectable` ahora muestra todos los atributos (ID, Name, CreatedAt, UpdatedAt, Version, Spec) — @Gabriel
+
+## [0.5.2] - 2026-04-07
+
+### Correcciones
+- Fix en `Inspectable`: usar `send(:ID)` en vez de `ID` directamente para evitar `NameError` por interpretación como constante — @Gabriel
+
+## [0.5.1] - 2026-04-06
+
+### Mejoras internas
+- Refactor de logs en `Connection`: cambio de `duration_ms` a `duration_s` y de `status` a `http_status` para alinearse con estándares de observabilidad — @Gabriel
+- Precisión de duración mejorada usando segundos con 4 decimales — @Gabriel
+- Reestructuración de `skills.yml` para soportar variables de entorno en agentes y nuevas skills — @Gabriel
+
+## [0.5.0] - 2026-04-04
+
+### Nuevas funcionalidades
+- Skill de conocimiento empaquetada (`skill/`) para consumo via `skill-manager sync` — @Gabriel
+- Helper de testing documentado (`DockerSwarmHelpers`) con `stub_docker_find` y `stub_docker_list` — @Claude
+
+### Mejoras internas
+- README reescrito con instalación, más ejemplos de uso, y sección Documentación linkeando a `docs/` — @Claude
+- `docs/testing.md` reescrito: mockeo de CRUD, errores, helper reutilizable — @Claude
+- `docs/errors.md` completado con errores faltantes (NotAcceptable 406, RequestTimeout 408, BadGateway 502) — @Claude
+- Cross-references bidireccionales entre todos los docs — @Claude
+- Centralización de logging en `LogHelper` con masking de campo `Data` para Secret/Config — @Gabriel
+- Gemspec actualizado para empaquetar `skill/**/*` en el `.gem` — @Claude
+
+## [0.4.0] - 2026-03-31
+
+### Nuevas funcionalidades
+- Dependabot configurado para actualizaciones semanales de gemas y mensuales de GitHub Actions — @Gabriel
+- Integración de `rubocop-rails-omakase` y verificación RuboCop en CI — @Gabriel
+- Tests de infraestructura robustos para `Connection`, `Configuration` y Middlewares — @Gabriel
+- Documentación YARD en todos los modelos y componentes core — @Gabriel
+- Concern `Inspectable` para inspección legible en consola (ID, Name, Image) — @Gabriel
+
+### Mejoras internas
+- Memoización de accessors en `Base` para optimizar procesamiento de recursos — @Gabriel
+- Refactor de logs a `Concerns::Loggable` para DRY en Service, Task y Container — @Gabriel
+- Branch default renombrado de `master` a `main` — @Gabriel
+
+### Correcciones
+- Casting automático de timeouts y retries para prevenir `TypeError` con ENV variables — @Gabriel
+- Orden de carga interno reorganizado para resolver issues de inicialización — @Gabriel
+
+## [0.3.0] - 2026-03-31
+
+### Nuevas funcionalidades
+- Timeouts y retries configurables: `read_timeout`, `write_timeout`, `connect_timeout`, `max_retries` — @Gabriel
+- `RequestEncoder` soporta `application/x-www-form-urlencoded` y `multipart/form-data` — @Gabriel
+- `ResponseJSONParser` aplica `with_indifferent_access` recursivo en Arrays — @Gabriel
+
+## [0.2.0] - 2026-03-31
+
+### Nuevas funcionalidades
+- Logging estructurado KV (`component`, `event`, `source`, `duration_ms`) estándar Wispro — @Gabriel
+- Reloj monotónico para medición precisa de duración de requests — @Gabriel
+- Masking automático de claves sensibles en logs — @Gabriel
+- Soporte para Unix sockets y HTTP/TCP via `socket_path` — @Gabriel
+- `Network.update` implementado — @Gabriel
+- `log_level` configurable en runtime — @Gabriel
+- Error `TooManyRequests` (429) — @Gabriel
+- Tests de integración para Service, Node, Task, Swarm, System, Image y Container — @Gabriel
+
+### Mejoras internas
+- Modelos movidos a `lib/docker_swarm/models/` — @Gabriel
+- `Base.all` normalizado para respuestas envueltas (`root_key`) — @Gabriel
+- Método `logs` estandarizado a nivel de instancia — @Gabriel
+- `Swarm` y `System` heredan de `Base` con atributos dinámicos — @Gabriel
+- Jerarquía de errores reestructurada bajo `DockerSwarm::Error` con aliases — @Gabriel
+
+### Correcciones
+- Excon ya no envuelve excepciones de negocio en `Excon::Error::Socket` — @Gabriel
+- `Volume.all` corregido para la respuesta envuelta de Docker — @Gabriel
+- `Gateway_Timeout` renombrado a `GatewayTimeout` — @Gabriel
+- Entry point `lib/docker-swarm.rb` agregado para Bundler/Rails — @Gabriel
+- Validaciones de `Service` relajadas para flexibilidad en tests — @Gabriel
+
+---
+
+## [0.1.0] - Early 2026
+- Release inicial con ORM básico para Services, Networks y Volumes — @Gabriel

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gabriel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,145 +1,66 @@
-# Docker Swarm Gem
+# docker-swarm
 
 [![Gem Version](https://badge.fury.io/rb/docker-swarm.svg)](https://badge.fury.io/rb/docker-swarm)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-`docker-swarm` es un ORM ligero y cliente API robusto para interactuar con Docker Swarm desde Ruby. Diseñado para sentirse familiar a los desarrolladores de Rails, utiliza `ActiveModel` para ofrecer una interfaz limpia y potente con estándares de observabilidad de Wispro.
+## Propósito
 
-## Instalacion
+ORM ligero y cliente API para Docker Swarm en Ruby. Expone las primitivas del Docker Engine (Service, Node, Task, Container, Network, Volume, Config, Secret, Swarm, System, Image) como modelos `ActiveModel` con CRUD, validaciones y logs estructurados KV. Excon directo sobre el socket Unix (default) o TCP.
 
-Agrega la gema a tu `Gemfile`:
+## Setup
 
 ```ruby
+# Gemfile
 gem 'docker-swarm', '~> 0.6'
 ```
 
-Y ejecuta:
-
 ```bash
 bundle install
 ```
 
-## Quick Start
+Quick start:
 
 ```ruby
 require 'docker_swarm'
 
-# Configurar (opcional, usa defaults razonables)
 DockerSwarm.configure do |config|
-  config.socket_path = "unix:///var/run/docker.sock"
+  config.socket_path = "unix:///var/run/docker.sock"  # default
   config.log_level   = Logger::INFO
-  config.max_retries = 3
 end
 
-# Verificar conectividad
-DockerSwarm::System.up  # => "OK"
-
-# Listar servicios
-services = DockerSwarm::Service.all
-services.each { |s| puts "#{s.ID}: #{s.Spec[:Name]}" }
-```
-
-## Uso
-
-### Crear un servicio
-
-```ruby
-service = DockerSwarm::Service.create(
-  Name: "my-webapp",
-  TaskTemplate: {
-    ContainerSpec: { Image: "nginx:latest" }
-  }
-)
-puts service.ID
-```
-
-### Actualizar (maneja Version.Index automaticamente)
-
-```ruby
-service = DockerSwarm::Service.find("svc-id")
-service.update(Mode: { Replicated: { Replicas: 3 } })
-```
-
-### Eliminar
-
-```ruby
-service.destroy  # graceful: retorna nil si ya no existe
-```
-
-### Reiniciar
-
-```ruby
-service.restart  # equivalente a docker service update --force
-```
-
-### Logs
-
-```ruby
-puts service.logs(stdout: 1, stderr: 1)
+DockerSwarm::System.up                  # => "OK"
+DockerSwarm::Service.all                # => [#<Service ...>, ...]
+DockerSwarm::Service.find("svc-id")     # => nil si no existe
 ```
 
-### Filtros
+Para el contrato completo de la gema (símbolos públicos, gotchas, integración) ver [`skill/SKILL.md`](skill/SKILL.md).
 
-```ruby
-DockerSwarm::Service.all(label: ["env=production"])
-DockerSwarm::Node.all(role: ["manager"])
-DockerSwarm::Container.all(status: ["running"])
-```
+## Índice de artefactos
 
-### Sistema y Cluster
+Documentación normada (RFC-001) por capa:
 
-```ruby
-DockerSwarm::System.info     # informacion del daemon
-DockerSwarm::System.version  # version de Docker
-DockerSwarm::System.df       # uso de disco
-DockerSwarm::Swarm.show      # informacion del cluster
-```
+| Capa | Artefacto | Estado |
+|---|---|---|
+| Datos | — | `n/a` (gema sin DB) |
+| Glosario | [`docs/glossary/glossary.md`](docs/glossary/glossary.md) | F1 completo |
+| Comportamiento | [`docs/behavior/behavior.md`](docs/behavior/behavior.md) | F1 backfill on-demand (8 flujos) |
+| API (operaciones) | — | F2 pendiente; contrato resumido inline en `skill/SKILL.md` |
+| Interfaz | — | F2 pendiente; contrato resumido inline en `skill/SKILL.md` |
+| Topología | — | F2 pendiente |
+| Eventos | — | `n/a` (la gema no emite eventos) |
 
-### Manejo de errores
+`n/a` = no aplica al tipo de repo. F2 pendiente = capa declarada en la RFC pero todavía no implementada en `dev-structure`; el contenido relevante vive transitoriamente en `skill/SKILL.md` (RFC-008 §2 coexistencia transitoria).
 
-```ruby
-begin
-  DockerSwarm::Service.create(Name: "web", TaskTemplate: { ... })
-rescue DockerSwarm::Conflict => e
-  puts "Nombre duplicado"
-rescue DockerSwarm::Communication => e
-  puts "Docker inalcanzable: #{e.message}"
-end
-```
-
-## Configuracion
-
-```ruby
-DockerSwarm.configure do |config|
-  config.socket_path     = "unix:///var/run/docker.sock"  # o http://host:port
-  config.logger          = Logger.new($stdout)
-  config.log_level       = Logger::INFO
-  config.read_timeout    = 60    # segundos
-  config.write_timeout   = 60
-  config.connect_timeout = 10
-  config.max_retries     = 3
-end
-```
-
-Ver [Guia de Configuracion](docs/configuration.md) para opciones avanzadas, Rails integration y observabilidad.
-
-## Documentacion
-
-- [Modelos (ORM)](docs/models.md) — Todos los modelos, concerns y ciclo de vida
-- [Configuracion](docs/configuration.md) — Opciones, observabilidad y seguridad
-- [Manejo de Errores](docs/errors.md) — Jerarquia de excepciones y uso
-- [Cliente API](docs/api.md) — Acceso de bajo nivel y middlewares
-- [Testing](docs/testing.md) — Estrategias de mocking para tus tests
-
-## Contribuir
-
-Las contribuciones son bienvenidas. Por favor, lee `CLAUDE.md` para las guias de desarrollo.
+## Desarrollo
 
 ```bash
-bundle exec rspec       # tests
-bundle exec rubocop -a  # linting
+bundle exec rspec --tag ~type:integration   # unit suite
+bundle exec rspec                            # incluye integration (requiere Docker socket)
+bundle exec rubocop -a                       # lint
 ```
 
+Release: `/gem-release` (publica a RubyGems via GitHub Action al tag `v*`).
+
 ## Licencia
 
-Este proyecto esta bajo la licencia MIT.
+MIT — ver [LICENSE](LICENSE).

data/docs/behavior/behavior.md

@@ -0,0 +1,243 @@
+# Comportamiento — docker-swarm
+
+> meta: artefacto · RFC-007 · generado dev-enrich · anclado a `a4e3129` · cobertura: backfill on-demand inicial (8 flujos load-bearing)
+
+## 1. Resumen
+
+Flujos de ejecución load-bearing de `docker-swarm`: cómo se materializan en runtime las operaciones CRUD, el control de concurrencia optimista de Docker, la política de retries post-fix correctness, y el mapeo de errores. Render Mermaid sequenceDiagram/flowchart por flujo.
+
+## 2. Cobertura declarada
+
+### Documentados (8)
+
+1. `Service.create` + reload
+2. `Service.update` con `Version.Index`
+3. `Service.restart` (force update)
+4. `Model.destroy` (graceful 404)
+5. Política de retries por método HTTP
+6. Error mapping (HTTP status → excepción tipada)
+7. `Container.start` / `Container.stop`
+8. `Loggable#logs` streaming
+
+### No documentados (ausencia ≠ inexistencia, RFC-007)
+
+- Reconexión / reapertura de socket Unix (Excon nativo, fuera de nuestra superficie).
+- Flujo de configuración / boot (`DockerSwarm.configure`) — trivial, sin secuencia de interés.
+- Pull de imágenes con autenticación de registry (`X-Registry-Auth`) — **no implementado** en la gema (gap conocido).
+- `Container.create` — **no implementado** en F1 (intencional, ver glossary).
+
+## 3. Flujos
+
+### 3.1 `Service.create` + reload
+
+Crear un Service implica un POST seguido de un reload automático para hidratar la instancia con la respuesta completa de Docker (el endpoint `create` sólo devuelve `ID`).
+
+```mermaid
+sequenceDiagram
+    actor Caller
+    participant Service as DockerSwarm::Service
+    participant Api as DockerSwarm::Api
+    participant Conn as Connection
+    participant Docker as Docker Engine
+
+    Caller->>Service: Service.create(Name:, TaskTemplate:)
+    Service->>Service: new(attrs) → valid?
+    Service->>Api: request(:create, payload: payload_for_docker)
+    Api->>Conn: request(method: :post, path: services/create, body:)
+    Conn->>Docker: POST /services/create
+    Docker-->>Conn: 201 { ID: "abc" }
+    Conn-->>Service: { ID: "abc" }
+    Service->>Service: self.ID = "abc"
+    Service->>Api: request(:show, arguments: { id: "abc" })
+    Api->>Conn: request(method: :get, path: services/abc)
+    Conn->>Docker: GET /services/abc
+    Docker-->>Conn: 200 { ID, Spec, Version, ... }
+    Conn-->>Service: full payload
+    Service-->>Caller: hydrated Service instance
+```
+
+**Notas load-bearing:**
+- `valid?` corre antes del POST. Si falla, `save` retorna `false` sin tocar el API.
+- El POST no se reintenta automáticamente: ver §3.5 (retry policy).
+- El reload usa `find` interno; si Docker devuelve 404 entre create+show (caso extremo), el reload no se realiza y la instancia queda sólo con `ID`.
+
+### 3.2 `Service.update` con `Version.Index`
+
+Updates atómicos sobre Service/Node/Network requieren enviar el `Version.Index` actual como query param. Sin él, Docker rechaza con 500. La gema lo extrae automáticamente de `self.Version["Index"]`.
+
+```mermaid
+sequenceDiagram
+    actor Caller
+    participant Model as Service/Node/Network
+    participant Api
+    participant Docker as Docker Engine
+
+    Caller->>Model: model.update(Mode: { Replicated: { Replicas: 3 } })
+    Model->>Model: assign_attributes(new_attrs)  -- Spec deep_merge si aplica
+    Model->>Model: valid?
+    Model->>Api: request(:update, id:, query: { version: Version.Index }, payload:)
+    Api->>Docker: POST /services/abc/update?version=42
+    alt version coincide
+        Docker-->>Api: 200 OK
+        Api-->>Model: success
+        Model-->>Caller: true
+    else version stale
+        Docker-->>Api: 500 update out of sequence
+        Api->>Api: ErrorHandler → raise InternalServerError
+        Api-->>Caller: DockerSwarm::Error::InternalServerError
+    end
+```
+
+**Notas load-bearing:**
+- `assign_attributes` muta el estado local **antes** de validar/enviar. Si el update falla, la instancia queda mutada (gotcha conocido, ver SKILL.md).
+- `Spec` se mergea con `deep_merge`; otros atributos top-level se asignan directo.
+- El update **no** hace reload automático (a diferencia de `create`). El caller llama `reload` si necesita el `Version.Index` nuevo.
+
+### 3.3 `Service.restart` (force update)
+
+Reinicio sin downtime equivalente a `docker service update --force`: incrementa `ForceUpdate` del `TaskTemplate` para que Docker recree todas las tasks.
+
+```mermaid
+flowchart LR
+    A["service.restart"] --> B["lee Spec.TaskTemplate.ForceUpdate"]
+    B --> C["current = ForceUpdate o 0 si nil"]
+    C --> D["update Spec: TaskTemplate: ForceUpdate: current+1"]
+    D --> E["POST /services/id/update?version=X"]
+    E --> F["Docker recrea tasks"]
+```
+
+**Notas load-bearing:**
+- Usa el flujo §3.2 internamente — hereda Version.Index, retry-policy y error-mapping.
+- Si `Spec` o `TaskTemplate` no existen aún (instancia nueva sin reload), `current = 0`.
+
+### 3.4 `Model.destroy` (graceful 404)
+
+DELETE con tolerancia a 404: si el recurso ya fue eliminado, `destroy` retorna `nil` en vez de raise.
+
+```mermaid
+sequenceDiagram
+    actor Caller
+    participant Model
+    participant Api
+    participant Docker
+
+    Caller->>Model: model.destroy
+    Model->>Api: request(:destroy, id:)
+    Api->>Docker: DELETE /services/abc
+    alt recurso existe
+        Docker-->>Api: 200 OK
+        Api-->>Model: true
+        Model-->>Caller: true
+    else 404 (ya eliminado)
+        Docker-->>Api: 404 Not Found
+        Api->>Api: ErrorHandler → raise NotFound
+        Model->>Model: rescue Errors::NotFound
+        Model-->>Caller: nil
+    end
+```
+
+**Notas load-bearing:**
+- Tanto `Model.destroy(id)` (class method) como `model.destroy` (instance) capturan `NotFound`.
+- 409 (`Conflict` — recurso en uso) **no** se captura; el caller debe manejarlo si aplica.
+
+### 3.5 Política de retries por método HTTP
+
+Post-fix correctness (PR #3): los retries automáticos sólo aplican a métodos seguros. POST/PATCH no reintentan para evitar duplicados.
+
+```mermaid
+flowchart TD
+    Req[Connection#request<br/>method, path, body] --> Class{IDEMPOTENT_METHODS<br/>incluye method?}
+    Class -- get/head/put/delete/options --> Safe[idempotent: true<br/>retries: max_retries]
+    Class -- post/patch/otro --> Write[idempotent: false<br/>retries: 0]
+    Safe --> Excon[Excon.request<br/>retry on Socket/Timeout]
+    Write --> ExconNoRetry[Excon.request<br/>sin retry]
+```
+
+**Notas load-bearing:**
+- Si el socket se cierra durante la lectura de la respuesta de un `services/create`, **no** se replica — la instancia queda en error y el caller decide.
+- `max_retries` (default 3) sólo afecta lecturas/idempotentes.
+
+### 3.6 Error mapping (status → excepción)
+
+`ErrorHandler` interpreta status HTTP 4xx/5xx y emite excepción tipada de la jerarquía `DockerSwarm::Error`.
+
+```mermaid
+flowchart TD
+    Resp[Response status, body] --> Range{status range}
+    Range -- 200-299 --> Pass[pass to next middleware]
+    Range -- 4xx/5xx --> Log[log business_error<br/>KV format]
+    Log --> Map{status}
+    Map -- 400 --> BadRequest
+    Map -- 401 --> Unauthorized
+    Map -- 403 --> Forbidden
+    Map -- 404 --> NotFound
+    Map -- 406 --> NotAcceptable
+    Map -- 408 --> RequestTimeout
+    Map -- 409 --> Conflict
+    Map -- 422 --> UnprocessableEntity
+    Map -- 429 --> TooManyRequests
+    Map -- 500 --> InternalServerError
+    Map -- 502 --> BadGateway
+    Map -- 503 --> ServiceUnavailable
+    Map -- 504 --> GatewayTimeout
+    Map -- otro --> GenericError[Error HTTP N]
+```
+
+**Notas load-bearing:**
+- Antes de raise, `ErrorHandler` emite un evento `business_error` en formato KV con `status`, `message`, `method`, `path`. Permite diagnosticar sin abrir backtrace.
+- Errores de red (no HTTP) se mapean a `DockerSwarm::Error::Communication` en `Connection#request`.
+- El mensaje de la excepción viene del body parseado: prefiere `body["message"]`, luego `body["error"]`, luego el body completo.
+
+### 3.7 `Container.start` / `Container.stop`
+
+Operaciones específicas sin payload (POST a endpoint dedicado).
+
+```mermaid
+sequenceDiagram
+    actor Caller
+    participant Container as DockerSwarm::Container
+    participant Api
+    participant Docker
+
+    Caller->>Container: container.start
+    Container->>Api: request(:start, id:)
+    Api->>Docker: POST /containers/abc/start
+    Docker-->>Api: 204 No Content
+    Api-->>Container: ""
+    Container-->>Caller: true
+```
+
+Mismo patrón para `stop`. POST sin body → no se reintenta automáticamente (§3.5).
+
+### 3.8 `Loggable#logs` streaming
+
+Obtención de logs raw para Service/Task/Container.
+
+```mermaid
+sequenceDiagram
+    actor Caller
+    participant Model as Service/Task/Container
+    participant Api
+    participant Docker
+
+    Caller->>Model: model.logs(stdout: 1, stderr: 1, follow: 0)
+    Model->>Api: request(:logs, id:, query: { stdout:, stderr:, follow: })
+    Api->>Docker: GET /services/abc/logs?stdout=1&stderr=1
+    Docker-->>Api: 200 raw stream (text/plain)
+    Api-->>Model: raw body
+    Model-->>Caller: String
+```
+
+**Notas load-bearing:**
+- El body se devuelve sin parseo (no es JSON; `ResponseJSONParser` lo respeta porque Content-Type no es `application/json`).
+- `follow: 1` mantiene la conexión abierta — el caller debe manejar el stream/timeout.
+
+## 4. Cobertura y fronteras
+
+- **Cobertura inicial (RFC-007 backfill on-demand):** 8 flujos load-bearing documentados. Esta gema es chica; el backfill completo es factible y se hace ahora.
+- **Frontera con glosario:** términos (Service, Spec, Version.Index, etc.) viven en [`docs/glossary/glossary.md`](../glossary/glossary.md). Esta capa documenta secuencias, no significado.
+- **Frontera con configuración:** `DockerSwarm.configure` es boot, no flujo de negocio. No se diagrama.
+- **No localizable / fuera de alcance:**
+  - Lógica interna de Excon (retry timing, socket pool) — vive en Excon, no se inventa diagrama.
+  - Flujo de auth registry para `Image.create` — la gema **no implementa** `X-Registry-Auth` (gap, no flujo a documentar).
+- **Cadencia incremental a partir de acá:** sólo se diagrama un flujo cuando un PR lo toca o agrega. No barrido retroactivo de legacy.