docker-swarm 0.7.2 → 0.9.0

data/docs/glossary/glossary.md

@@ -1,6 +1,6 @@
 # Glosario — docker-swarm
 
-> meta: artefacto · RFC-009 · generado dev-enrich · anclado a `a4e3129` · cobertura: completo inicial (primitivas Docker + arquitectura interna); no se acrecienta sin tocar el flujo/concepto
+> meta: artefacto · RFC-009 · generado dev-enrich · anclado a `v0.9.0` · cobertura: completo inicial (primitivas Docker + arquitectura interna); no se acrecienta sin tocar el flujo/concepto
 
 ## 1. Resumen
 
@@ -8,81 +8,81 @@ Términos de negocio que la gema `docker-swarm` materializa. Dos grupos: **primi
 
 ## 2. Términos
 
-### Service
+## Service
 
 Servicio de Docker Swarm: definición declarativa de un conjunto de tasks que corren en el cluster. La gema lo expone como CRUD completo + `restart` + `logs`. Update atómico vía `Version.Index`.
 **Binding:** [`DockerSwarm::Service`](../../lib/docker_swarm/models/service.rb)
 
-### Node
+## Node
 
 Miembro físico del cluster Swarm (manager o worker). Read-only desde el punto de vista de creación: los nodos se unen al swarm fuera de la gema; la gema sólo permite update (rol/disponibilidad) y destroy.
 **Binding:** [`DockerSwarm::Node`](../../lib/docker_swarm/models/node.rb)
 
-### Task
+## Task
 
 Unidad de ejecución de un Service en un Node específico. Read-only: las tasks se generan automáticamente por el orquestador a partir del Spec del Service. La gema sólo permite listar/inspeccionar/obtener logs.
 **Binding:** [`DockerSwarm::Task`](../../lib/docker_swarm/models/task.rb)
 
-### Container
+## Container
 
-Container Docker standalone (no Swarm). La gema expone start/stop/destroy/logs sobre containers existentes. Creación intencionalmente fuera de scope F1 — el caso de uso primario de la gema es Swarm.
+Container Docker standalone (no Swarm). La gema expone create/start/stop/destroy/logs. La creación estuvo fuera de scope en F1 —el caso de uso primario de la gema es Swarm— y entró con ADR-025 cláusula 1: operar datos on-host durante una migración necesita un **helper container efímero** con nombre determinista, que es lo que habilita adoptarlo en un reintento en vez de duplicarlo.
 **Binding:** [`DockerSwarm::Container`](../../lib/docker_swarm/models/container.rb)
 
-### Image
+## Image
 
-Imagen Docker (registry o local). La gema cubre listar, pull (`create`) y destroy. Build local no cubierto (no caso de uso de orquestación).
+Imagen Docker (registry o local). La gema cubre listar, pull (`Image.pull`, explícito y síncrono) y destroy. Build local no cubierto (no caso de uso de orquestación). El `create` genérico se retiró: `Image` ya no es Creatable.
 **Binding:** [`DockerSwarm::Image`](../../lib/docker_swarm/models/image.rb)
 
-### Network
+## Network
 
 Red Docker (overlay para Swarm, bridge para Container). CRUD completo. Update soporta conectar/desconectar containers.
 **Binding:** [`DockerSwarm::Network`](../../lib/docker_swarm/models/network.rb)
 
-### Volume
+## Volume
 
 Volumen Docker (named volume). CRUD sin update (Docker no soporta update de Volume). La respuesta del index viene envuelta en `{"Volumes": [...]}` — manejado vía `root_key`.
 **Binding:** [`DockerSwarm::Volume`](../../lib/docker_swarm/models/volume.rb)
 
-### Config
+## Config
 
 Configuración inmutable distribuida en el cluster (archivos de configuración, manifests). CRUD sin update — Docker requiere recrear. Sólo Swarm.
 **Binding:** [`DockerSwarm::Config`](../../lib/docker_swarm/models/config.rb)
 
-### Secret
+## Secret
 
 Dato sensible distribuido en el cluster (passwords, tokens, certs). Misma semántica que Config pero el `Data` se filtra automáticamente en logs vía `LogHelper`. Sólo Swarm.
 **Binding:** [`DockerSwarm::Secret`](../../lib/docker_swarm/models/secret.rb)
 
-### Swarm
+## Swarm
 
 Cluster Docker Swarm como entidad singleton. Sólo `show` (info del cluster: ID, Version, Spec, JoinTokens). No CRUD — el cluster se inicializa/disuelve fuera de la gema.
 **Binding:** [`DockerSwarm::Swarm`](../../lib/docker_swarm/models/swarm.rb)
 
-### System
+## System
 
 Daemon Docker como entidad singleton. Métodos estáticos: `info`, `version`, `up` (ping), `df` (disk usage). Útil para health checks y observabilidad.
 **Binding:** [`DockerSwarm::System`](../../lib/docker_swarm/models/system.rb)
 
 ---
 
-### Base (ORM base)
+## Base (ORM base)
 
 Clase base de todos los modelos. Hereda de `ActiveModel::Model`. Provee accessors dinámicos PascalCase, `find`, `all`, `where`, `reload`, `payload_for_docker`. Centraliza el patrón ORM contra Docker Engine API.
 **Binding:** [`DockerSwarm::Base`](../../lib/docker_swarm/base.rb)
 
-### Concern
+## Concern
 
 Mixin (`ActiveSupport::Concern`) que agrega capacidad CRUD/auxiliar a un modelo. La gema define cinco concerns ortogonales: cada modelo incluye los que aplican a su semántica Docker.
 
 | Concern | Símbolo | Aplica a |
 |---|---|---|
-| Creatable | [`DockerSwarm::Concerns::Creatable`](../../lib/docker_swarm/concerns/creatable.rb) | Service, Network, Volume, Config, Secret, Image |
+| Creatable | [`DockerSwarm::Concerns::Creatable`](../../lib/docker_swarm/concerns/creatable.rb) | Service, Network, Volume, Config, Secret |
 | Updatable | [`DockerSwarm::Concerns::Updatable`](../../lib/docker_swarm/concerns/updatable.rb) | Service, Node, Network |
 | Deletable | [`DockerSwarm::Concerns::Deletable`](../../lib/docker_swarm/concerns/deletable.rb) | Service, Node, Container, Network, Volume, Config, Secret, Image |
 | Loggable | [`DockerSwarm::Concerns::Loggable`](../../lib/docker_swarm/concerns/loggable.rb) | Service, Task, Container |
 | Inspectable | [`DockerSwarm::Concerns::Inspectable`](../../lib/docker_swarm/concerns/inspectable.rb) | Todos (vía Base) |
 
-### Middleware
+## Middleware
 
 Capa Excon en el stack del cliente HTTP. Tres middlewares custom: serialización de body, parsing de respuesta con indifferent access, mapeo de status a excepción tipada.
 
@@ -92,32 +92,32 @@ Capa Excon en el stack del cliente HTTP. Tres middlewares custom: serialización
 | ResponseJSONParser | [`DockerSwarm::Middleware::ResponseJSONParser`](../../lib/docker_swarm/middleware/response_json_parser.rb) | Parsea JSON y aplica `with_indifferent_access` |
 | ErrorHandler | [`DockerSwarm::Middleware::ErrorHandler`](../../lib/docker_swarm/middleware/error_handler.rb) | Mapea 4xx/5xx → `DockerSwarm::Error::*` + log `business_error` |
 
-### Connection
+## Connection
 
 Wrapper sobre el cliente Excon. Memoiza la conexión, aplica timeouts/retries de configuración, clasifica errores idempotentes vs no-idempotentes (post-fix correctness), y emite logs KV.
 **Binding:** [`DockerSwarm::Connection`](../../lib/docker_swarm/connection.rb)
 
-### Dynamic Accessor
+## Dynamic Accessor
 
 Mecanismo por el cual los modelos exponen atributos no declarados. Docker Engine evoluciona y agrega campos: la gema usa `method_missing` + cache en `defined_attributes` (Set) para responder a cualquier campo PascalCase de la respuesta sin requerir update del código.
 **Binding:** [`DockerSwarm::Base#method_missing`](../../lib/docker_swarm/base.rb), [`DockerSwarm::Base.defined_attributes`](../../lib/docker_swarm/base.rb)
 
-### Spec deep_merge
+## Spec deep_merge
 
 Estrategia de actualización parcial del campo `Spec` de un modelo. En vez de reemplazar Spec completo, `assign_attributes` hace `deep_merge` cuando la key es `Spec` y ambos valores son Hash. Razón: updates parciales no pierden campos anidados no tocados.
 **Binding:** [`DockerSwarm::Base#assign_attributes`](../../lib/docker_swarm/base.rb)
 
-### Version.Index
+## Version.Index
 
 Mecanismo de control de concurrencia optimista de Docker para updates atómicos. Cada Service/Node tiene `Version.Index` que incrementa en cada cambio. Update requiere enviar el index actual como query param; si no coincide, Docker rechaza (500). La gema lo extrae automáticamente en `Updatable#update`.
 **Binding:** [`DockerSwarm::Concerns::Updatable#update`](../../lib/docker_swarm/concerns/updatable.rb)
 
-### LogHelper
+## LogHelper
 
 Módulo de formateo de logs en KV (`key=value`) con masking automático de claves sensibles. La regex (`password|pass|passwd|secret|token|api_key|auth|\bdata\b`) reemplaza valores por `[FILTERED]`. `\bdata\b` evita falsos positivos en `metadata`/`database`.
 **Binding:** [`DockerSwarm::LogHelper`](../../lib/docker_swarm/log_helper.rb)
 
-### payload_for_docker
+## payload_for_docker
 
 Transformación interna que prepara un modelo para enviarlo al API: descarta atributos internos (`ID`/`Version`/`CreatedAt`/`UpdatedAt`), extrae el contenido de `Spec` al root y mergea otros campos top-level. Resultado: el payload que Docker espera para `create`/`update`.
 **Binding:** [`DockerSwarm::Base#payload_for_docker`](../../lib/docker_swarm/base.rb)
@@ -126,7 +126,6 @@ Transformación interna que prepara un modelo para enviarlo al API: descarta atr
 
 | Término | Inferencia | Confidence | Verificar |
 |---|---|---|---|
-| Container | "creación intencionalmente fuera de scope F1" | inferred | ¿se quiere documentar como decisión explícita o como gap a cubrir? |
 | Spec deep_merge | "razón: updates parciales no pierden campos" | declared | confirmado en CLAUDE.md decisión arquitectura |
 | Dynamic Accessor | "Docker evoluciona y agrega campos" | declared | confirmado en CLAUDE.md decisión arquitectura |
 
@@ -138,4 +137,5 @@ Transformación interna que prepara un modelo para enviarlo al API: descarta atr
 - **Fuera de alcance:**
   - Términos técnicos puros sin significado de negocio (ej: `instance_values`, `attr_accessor`) — son detalles de implementación, no contrato.
   - Glossary del Docker Engine API (cómo funciona internamente Swarm, raft, gossip) — vive en docs de Docker, no se duplica acá.
+- **Inferencia resuelta (2026-08-03):** §3 registraba como `inferred` la pregunta de si *"creación intencionalmente fuera de scope F1"* era una decisión de alcance o un gap a cubrir. Quedó resuelta: **era una decisión de alcance** (Swarm-first), y ADR-025 cláusula 1 **amplió el alcance** al aparecer un caso de uso real (el helper container efímero de la migración del ACS). La fila salió de §3 porque ya no es una inferencia pendiente.
 - **Cadencia:** incremental por PR a partir de acá; ausencia ≠ inexistencia (RFC-009).

data/docs/interface/interface.md

@@ -0,0 +1,121 @@
+# Interfaz — docker-swarm
+
+> meta: artefacto · RFC-004 · generado arch-structure · anclado a `v0.9.0` · cobertura: API Ruby pública de la gema (`lib/docker_swarm/**`); símbolos internos marcados en §4
+
+## 1. Resumen
+
+API Ruby pública de la gema. Entrypoint `DockerSwarm` (config + cliente HTTP). 11 modelos `ActiveModel`-compatibles heredan de `DockerSwarm::Base` y mezclan concerns (`Creatable`/`Updatable`/`Deletable`/`Loggable`). Atributos vía accessors dinámicos PascalCase (`method_missing`). Jerarquía de errores en `DockerSwarm::Error` (detalle en [`docs/errors/errors.md`](../errors/errors.md)).
+
+## 2. Cuerpo
+
+Proyección RBS-conceptual: `símbolo · tipo · nota` (raíz → profundidad → alfabético). Firmas aplanadas; el wire-schema de los atributos PascalCase no es estático (ver §4).
+
+### Módulo raíz `DockerSwarm`
+
+| símbolo | tipo | nota |
+|---|---|---|
+| `DockerSwarm` | módulo | namespace raíz |
+| `DockerSwarm::VERSION` | constante | `"0.8.0"` (`version.rb`) |
+| `DockerSwarm.configuration` | attr (r/w) | instancia de `Configuration`; lazy-init en `configure`/`connection` |
+| `DockerSwarm.configure { \|config\| ... }` | método de módulo | crea/yields `Configuration`; aplica `log_level` al logger; resetea la conexión memoizada |
+| `DockerSwarm.connection` | método de módulo | `Connection` memoizada (auto-`configure` si falta) |
+| `DockerSwarm.request(options = {})` | método de módulo | delega en `connection.request`; entrypoint de bajo nivel (escape hatch para llamadas crudas) |
+
+### `DockerSwarm::Configuration` (`configuration.rb`)
+
+| símbolo | tipo | nota |
+|---|---|---|
+| `#socket_path` | attr (r/w) | default `"unix:///var/run/docker.sock"` |
+| `#logger` | attr (r/w) | default `Logger.new($stdout)` |
+| `#log_level` | attr (r/w) | default `Logger::INFO` |
+| `#read_timeout` / `#read_timeout=` | attr (r) + setter | default `60.0`; setter castea `to_f` |
+| `#write_timeout` / `#write_timeout=` | attr (r) + setter | default `60.0`; setter castea `to_f` |
+| `#connect_timeout` / `#connect_timeout=` | attr (r) + setter | default `10.0`; setter castea `to_f` |
+| `#max_retries` / `#max_retries=` | attr (r) + setter | default `3`; setter castea `to_i` |
+
+Inventario completo de opciones: [`docs/config/configuracion.md`](../config/configuracion.md).
+
+### `DockerSwarm::Base` (`base.rb`) — base de los modelos
+
+`include ActiveModel::Model`, `include Concerns::Inspectable`.
+
+| símbolo | tipo | nota |
+|---|---|---|
+| `.resource_name` | método de clase | `name.demodulize.downcase.pluralize`; override en `Swarm`/`System` |
+| `.routes` | método de clase | `Api::ENDPOINTS[resource_name.to_sym]` |
+| `.root_key` | método de clase | `nil` por default; override `"Volumes"` en `Volume` |
+| `.defined_attributes` | método de clase | `Set` de accessors ya definidos (interno; cache de `method_missing`) |
+| `.all(filters = {})` | método de clase | `GET index`; mapea a instancias; aplica `root_key`; `[]` si vacío |
+| `.find(id)` | método de clase | `GET show`; `nil` si `Errors::NotFound` |
+| `.where(filters)` | método de clase | alias de `all` |
+| `#initialize(attributes = {})` | método de instancia | `assign_attributes` si presente |
+| `#assign_attributes(new_attributes)` | método de instancia | normaliza `Id`→`ID`; `deep_merge` del campo `Spec`; `ArgumentError` si no es Hash |
+| `#attributes` | método de instancia | `instance_values` sin internos de ActiveModel |
+| `#serializable_hash` / `#as_json` | método de instancia | == `attributes` |
+| `#payload_for_docker` | método de instancia | descarta `ID/Version/CreatedAt/UpdatedAt`; aplana `Spec` al root |
+| `#persisted?` | método de instancia | `ID` presente |
+| `#id` | método de instancia | == `self.ID` |
+| `#reload` | método de instancia | re-`find` por `id` y re-asigna |
+| `#method_missing` / `#respond_to_missing?` | método de instancia | accessors dinámicos PascalCase (atributos del recurso Docker) |
+
+### Concerns (`concerns/*.rb`)
+
+| símbolo | tipo | nota |
+|---|---|---|
+| `Concerns::Creatable.create(attributes = {}, **opts)` | método de clase (mixin) | `new` + `save`; retorna la instancia. `opts` reservado `registry_auth:` (→ header `X-Registry-Auth`); el resto se pliega como atributos |
+| `Concerns::Creatable#save(registry_auth: nil)` | método de instancia | `false` si `!valid?`; `update` si `persisted?`; si no `POST create` + `reload`. `registry_auth` viaja como header, nunca en el payload. Los `create_query_params` del modelo viajan por query string y se **excluyen** del payload |
+| `Concerns::Creatable.create_query_params` | método de clase (mixin) | `[]` por default; override por modelo. Atributos que el Engine toma por query string en el `create` y **descarta en silencio** si van en el body |
+| `Concerns::Creatable#query_params_for_docker` | método de instancia | los `create_query_params` seteados en esta instancia, con claves símbolo; `{}` si el modelo no declara ninguno |
+| `Concerns::Updatable#update(new_attributes = {}, **opts)` | método de instancia | extrae `Version.Index`; `false` si `!valid?`; `POST update` con `?version=`. `opts` reservado `registry_auth:` (header) / `registry_auth_from:` (query `registryAuthFrom`, `spec`\|`previous-spec`, excluyente con `registry_auth`); el resto se pliega como atributos |
+| `Concerns::Deletable.destroy(id)` | método de clase (mixin) | `DELETE destroy`; `nil` si `Errors::NotFound` |
+| `Concerns::Deletable#destroy` | método de instancia | delega en `.destroy(self.ID)` |
+| `Concerns::Loggable#logs(query_params = { stdout: 1, stderr: 1 })` | método de instancia | `GET logs`; retorna **texto ya demultiplexado** (sin los 8 bytes de cabecera por frame) — el demux lo hace `Middleware::LogStreamDemuxer`, el consumidor no ve el framing. Un stream de TTY (sin framing) pasa intacto |
+| `Concerns::Inspectable#inspect` | método de instancia | render legible (ID/Name/Version/Spec) |
+
+### Modelos (`models/*.rb`)
+
+| símbolo | tipo | concerns + métodos propios |
+|---|---|---|
+| `DockerSwarm::Service` | clase < Base | Creatable, Updatable, Deletable, Loggable; `#restart` (incrementa `TaskTemplate.ForceUpdate`); `create`/`update` aceptan `registry_auth:` (+ `update`: `registry_auth_from:`) para auth de registry privado |
+| `DockerSwarm::Node` | clase < Base | Updatable, Deletable (sin `create`: los nodos se unen fuera de la gema) |
+| `DockerSwarm::Task` | clase < Base | Loggable (read-only; generadas por el orquestador) |
+| `DockerSwarm::Container` | clase < Base | Creatable, Deletable, Loggable; `#start`, `#stop`; `.create_query_params == %w[name]` (el Engine toma el nombre por query string — en el body lo descarta en silencio y el container nace con nombre aleatorio). El `create` **no** es gap intencional desde ADR-025 cláusula 1 |
+| `DockerSwarm::Image` | clase < Base | Deletable + `.pull(image_reference, registry_auth: nil)`. **NO** es Creatable (`Image.create` retirado sin alias). `.pull` = pull explícito síncrono: consume el stream NDJSON hasta EOF, eleva `DockerSwarm::Error` ante frame `error`/`errorDetail`, retorna `{ status: :pulled, image_ref:, digest? }` (sin `find` posterior) |
+| `DockerSwarm::Network` | clase < Base | Creatable, Updatable, Deletable |
+| `DockerSwarm::Volume` | clase < Base | Creatable, Deletable; `.root_key = "Volumes"` (respuesta wrapped) |
+| `DockerSwarm::Config` | clase < Base | Creatable, Deletable (sin `update`: recrear) |
+| `DockerSwarm::Secret` | clase < Base | Creatable, Deletable (sin `update`); `Data` filtrado en logs |
+| `DockerSwarm::Swarm` | clase < Base | `.resource_name = "swarm"`; `.show` (singleton, info del cluster) |
+| `DockerSwarm::System` | clase < Base | `.resource_name = "system"`; `.info`, `.version`, `.up`, `.df` (singleton) |
+
+### Superficie de bajo nivel / soporte
+
+| símbolo | tipo | nota |
+|---|---|---|
+| `DockerSwarm::Api::ENDPOINTS` | constante (frozen Hash) | mapa `recurso → {operación → {method, path}}` |
+| `DockerSwarm::Api.request(action:, arguments: {}, query_params: {}, payload: nil)` | método de clase | formatea el `path` y delega en `DockerSwarm.request` |
+| `DockerSwarm::Connection.new(socket_path, logger)` | clase | cliente Excon (Unix socket o TCP); `#request`, `#socket_path`, `#logger` |
+| `DockerSwarm::Connection::IDEMPOTENT_METHODS` | constante | `%i[get head put delete options]` (los únicos con retry) |
+| `DockerSwarm::LogHelper.format_kv(payload)` | método de módulo | formatea KV + masking de claves sensibles |
+| `DockerSwarm::LogHelper::SENSITIVE_KEYS` | constante (Regexp) | `password\|pass\|...\|\bdata\b` |
+| `DockerSwarm::RegistryAuth.resolve(registry_auth:, registry_auth_from:)` | método de módulo | traduce las opciones de auth a `[headers, query_params]` (`X-Registry-Auth` / `registryAuthFrom`); valida exclusión mutua + enum antes de la request. Usado por `Image.pull` / `#save` / `#update`; la credencial nunca toca payload ni estado del modelo |
+| `DockerSwarm::RegistryAuth::{HEADER, QUERY, FROM_VALUES}` | constantes | `"X-Registry-Auth"` · `:registryAuthFrom` · `%w[spec previous-spec]` |
+| `DockerSwarm::Error` + subclases + aliases + `DockerSwarm::Errors` | clases/módulo | jerarquía de errores — detalle en [`docs/errors/errors.md`](../errors/errors.md) |
+| `DockerSwarm::Middleware::{RequestEncoder, LogStreamDemuxer, ResponseJSONParser, ErrorHandler}` | clases | middlewares Excon; públicos por require pero de uso interno (ver §4) |
+| `DockerSwarm::Middleware::LogStreamDemuxer::{MULTIPLEXED_CONTENT_TYPE, RAW_CONTENT_TYPE, HEADER_SIZE, STREAM_TYPES}` | constantes | `"application/vnd.docker.multiplexed-stream"` · `"application/vnd.docker.raw-stream"` · `8` · `[0, 1, 2]` |
+
+## 3. Inferencias
+
+| afirmación | confidence | a verificar |
+|---|---|---|
+| `Connection`, `Api` y los `Middleware::*` son de uso **interno** (un consumidor normal usa los modelos, no estas clases) | inferred | son `public` en Ruby; no hay marca `@api private`. `DockerSwarm.request`/`Api` son el escape-hatch documentado en `skill/SKILL.md` |
+| `.defined_attributes` es interno (cache de `method_missing`), no superficie de consumo | inferred | público pero sin uso externo plausible |
+| Los atributos PascalCase (`service.Spec`, `service.Version`, …) son la superficie real de datos, pero su set depende de la respuesta del Docker Engine API | declared | `method_missing` define accessors on-demand; el shape lo fija Docker, no la gema |
+
+## 4. Cobertura y fronteras
+
+- **Wire-schema de atributos:** los modelos no declaran atributos estáticos — se materializan dinámicamente desde el JSON de Docker (`method_missing`). El shape de `Spec`/`TaskTemplate`/etc. es el del Docker Engine API v1.41, **fuera de este repo** (doc oficial Docker). `unspecified` acá a propósito.
+- **`interface` vs `operaciones` (RFC-003):** esta gema NO expone superficie HTTP/CLI/eventos propia → `docs/api/operaciones` es `n/a`. Su superficie pública ES esta interfaz Ruby. Lo que la gema *consume* (Docker Engine API) vive en [`docs/consumed/`](../consumed/docker-engine-api.md).
+- **Errores:** la jerarquía `DockerSwarm::Error` se cataloga en [`docs/errors/errors.md`](../errors/errors.md); acá solo se referencia.
+- **Símbolos internos:** `Connection`, `Api`, `Middleware::*`, `Base.defined_attributes` se listan por completitud pero no son API de consumo recomendada; un cambio en ellos no rompe el contrato del consumidor típico (que usa los modelos).
+- **Significado de negocio** de cada modelo/término → [`docs/glossary/glossary.md`](../glossary/glossary.md); secuencias → [`docs/behavior/behavior.md`](../behavior/behavior.md).

data/docs/release/release.md

@@ -0,0 +1,54 @@
+# Release — docker-swarm
+
+> meta: artefacto · RFC-014 · generado arch-structure + enriquecido arch-enrich · anclado a `v0.9.0` · cobertura: §a estructura completa (versión · changelog · build-trigger · patrón); §b enrich completa (deploy · rollback · ambientes · dueño)
+
+## 1. Resumen
+
+Gema Ruby publicada en RubyGems. Release por **tag `v*`**: el push del tag dispara el workflow `Publish to RubyGems` que hace `gem build` + `gem push`. Sin deploy de infraestructura (gema, no servicio): no hay `Dockerfile`, ni branches `production`/`staging`, ni ambientes.
+
+## 2. Cuerpo
+
+### §a Estructura (verificable del código)
+
+| campo | valor | fuente |
+|---|---|---|
+| versión actual | `0.9.0` | `lib/docker_swarm/version.rb` (`DockerSwarm::VERSION`) |
+| esquema de versión | SemVer (`MAJOR.MINOR.PATCH`) | `CHANGELOG.md` (breaking/mejoras/correcciones por bump) |
+| artefacto liberado | gema `docker-swarm` a RubyGems | `docker-swarm.gemspec` (`spec.name`), `.github/workflows/release.yml` |
+| changelog | `CHANGELOG.md`, formato Keep a Changelog, entradas fechadas por versión | `CHANGELOG.md` |
+| licencia | MIT | `docker-swarm.gemspec` (`spec.license`) |
+| build-trigger | push de tag `v*` | `.github/workflows/release.yml` (`on.push.tags: ['v*']`) |
+| **patrón de trigger (RFC-014)** | **patrón 1** — publish per-repo-visible en workflow (tag → RubyGems) | `.github/workflows/release.yml` |
+| runner de release | `ubuntu-latest`, Ruby `3.4.4` | `.github/workflows/release.yml` |
+| pasos de publish | `gem build *.gemspec` + `gem push *.gem` | `.github/workflows/release.yml` |
+| credencial de publish | `secrets.RUBYGEMS_API_KEY` (env `RUBYGEMS_API_KEY`) | `.github/workflows/release.yml` |
+| MFA de publish | requerida (`rubygems_mfa_required = "true"`) | `docker-swarm.gemspec` (`spec.metadata`) |
+| Ruby mínimo del release | `>= 3.2.0` | `docker-swarm.gemspec` (`required_ruby_version`) |
+| contenido empaquetado | `lib`, `exe`, `skill`, `docs` + `README.md`, `CHANGELOG.md`, `LICENSE` | `docker-swarm.gemspec` (`spec.files`). Empaquetar `skill/` + `docs/` es **intencional**: la gema shippea su skill version-locked (RFC-008) y los artefactos de arquitectura para consumidores/agentes |
+| CI (no gatea el release) | workflow `Ruby` (`main.yml`) corre en push a `main` / PR: `rspec` (sin `type:integration`) + `rubocop`. **Independiente** de `release.yml` — el tag `v*` publica sin exigir que el CI haya pasado | `.github/workflows/main.yml` |
+| dependencias runtime | `activesupport >= 6.0`, `activemodel >= 6.0`, `excon >= 0.80` | `docker-swarm.gemspec` |
+
+### §b Deploy · rollback · ambientes · dueño (enrich)
+
+| dimensión | valor | nota |
+|---|---|---|
+| deploy | Publicación a RubyGems por `gem push` al pushear el tag `v*`. Los consumidores la reciben vía Bundler (`gem 'docker-swarm'`) tras la propagación del índice de RubyGems (~minutos) | "Deploy" para una gema = disponibilidad en RubyGems; no hay infraestructura que desplegar |
+| rollback | **Bump correctivo (preferido):** publicar un patch nuevo (`X.Y.Z+1`) con el fix. RubyGems **prohíbe** re-pushear el mismo número de versión (restricción técnica). `gem yank -v X.Y.Z` — RubyGems lo permite en cualquier momento (no hay restricción técnica), pero es **política del equipo** reservarlo a casos graves (secreto filtrado, gema rota/ininstalable) | Distinguir: el re-push prohibido es técnico de RubyGems; el yank restringido es decisión del equipo (un yank rompe a quien fijó esa versión → se prefiere avanzar) |
+| ambientes | No aplica: artefacto único publicado en RubyGems, sin staging/producción. El único "ambiente" es la versión instalada por cada consumidor | La matriz de compatibilidad la fija `required_ruby_version` (`>= 3.2.0`), no un ambiente de deploy |
+| dueño del release | Gabriel (mantenedor) — taggea `v*` y publica; @Pablo contribuye fixes | Derivado del historial de `CHANGELOG.md` y confirmado por el equipo |
+
+## 3. Inferencias
+
+| afirmación | confidence | a verificar |
+|---|---|---|
+| Patrón de trigger = 1 (publish per-repo-visible por tag), no patrón 3 (branch `production`/`staging`) | declared | `release.yml` sólo escucha `tags: v*`; no existen branches `production`/`staging` (`git branch -a`) |
+| Esquema de versión = SemVer | inferred | derivado del uso en `CHANGELOG.md` (0.7.0 marcó breaking changes); no hay política SemVer declarada explícita en el repo |
+| No hay deploy de infra | declared | ausencia de `Dockerfile`, `docker-compose.yml`, `helm/`, branches de ambiente — es gema, no servicio |
+| El gem se buildea bajo Ruby `3.4.4` aunque declara floor `>= 3.2.0` | declared | runner fijo en `release.yml` (`3.4.4`) vs `required_ruby_version` del gemspec (`>= 3.2.0`); no es defecto — el build no acopla el floor de compatibilidad |
+
+## 4. Cobertura y fronteras
+
+- **Estructura (§a) y enrich (§b) completas** al ancla `cccfe63`; significado de §b aportado por el mantenedor.
+- **Proceso operativo del release** (quién taggea, checklist, bump de versión) lo ejecuta la skill `gem-release`; este artefacto documenta el contrato, no el paso-a-paso de la skill.
+- **Trade-off conocido:** el release (`release.yml`, tag `v*`) **no exige** que el CI (`main.yml`) haya pasado — un tag publica aunque los tests fallen. Hoy el gate es de facto (el dev corre la suite antes de taggear), no forzado por el pipeline. Endurecerlo (exigir CI verde antes de publicar) es una mejora de proceso pendiente, no documentada como decisión formal.
+- **Fuera de alcance:** la config runtime de la gema vive en `docs/config/configuracion.md`; la suite y su gate CI en `docs/test/testing.md` (este artefacto sólo referencia el gate pre-release, no lo redefine).

data/docs/test/testing.md

@@ -0,0 +1,100 @@
+# Test — docker-swarm
+
+> meta: artefacto · RFC-013 · generado arch-structure + enriquecido arch-enrich · anclado a `v0.9.0` · cobertura: estructura de la suite (`spec/`, `.github/workflows/main.yml`); §e enriquecida, §f enriquecida, §g `unknown` (sin incidentes registrados), §h enriquecida
+
+## 1. Resumen
+
+Suite RSpec en dos niveles: **unit** (mockean `DockerSwarm::Api`/`Excon`, sin daemon) e **integration** (`type: :integration`, requieren un Docker daemon real). CI corre solo unit + RuboCop; integration es local/opt-in. Sin herramienta de coverage configurada.
+
+## 2. Cuerpo
+
+### a. Suites, frameworks y niveles
+
+Framework: **RSpec** (`~> 3.0`). `verify_partial_doubles = true` (mocks estrictos).
+
+| subdirectorio | propósito | nivel | helper |
+|---|---|---|---|
+| `spec/docker/swarm/*_spec.rb` | api, configuration, connection, log_helper, registry_auth | unit | `spec_helper` |
+| `spec/docker/swarm/middleware/*_spec.rb` | error_handler, log_stream_demuxer, request_encoder, response_json_parser | unit | `spec_helper` |
+| `spec/docker/swarm/models/*_spec.rb` | base, container, image, network, node, service, task + `shared_crud_spec` | unit | `spec_helper` |
+| `spec/integration/*_spec.rb` | containers, infra, security, services, system | integration | `integration_helper` |
+
+Tag de nivel: las integration declaran `RSpec.describe "...", type: :integration` (`spec/integration/*_spec.rb:5`). Las unit no llevan tag → se filtran con `~type:integration`.
+
+`shared_crud_spec.rb` = shared examples de CRUD reusados por los specs de modelo.
+
+### b. Comando de corrida
+
+| contexto | comando | qué corre |
+|---|---|---|
+| unit (local) | `bundle exec rspec --tag ~type:integration` | todo menos integration |
+| integration (local) | `bundle exec rspec` | incluye integration (requiere Docker socket; override `DOCKER_URL`) |
+| lint | `bundle exec rubocop` | rubocop-rails-omakase |
+| CI (`.github/workflows/main.yml`) | `bundle exec rspec --tag ~type:integration` + `bundle exec rubocop` | unit + lint, Ruby 3.4.4 |
+
+CI **no** corre integration (no hay daemon en el runner). Se dispara en push a `main` y en `pull_request`.
+
+### c. Fixtures / Factories
+
+- **Sin fixtures YAML ni FactoryBot.** Los datos de prueba se construyen inline en cada spec.
+- **Unit:** mockean `DockerSwarm::Api.request` (o `Excon`) con `and_return`/`and_raise` (stubs de respuesta Docker). `spec_helper` configura `socket_path = "unix:///tmp/docker.sock"` y logger a `/dev/null`.
+- **Integration:** crean recursos reales contra el daemon; helper `random_name(prefix)` (`integration_helper.rb:26`) genera nombres únicos con `SecureRandom.hex(4)` para evitar colisiones.
+
+### d. Configuración de coverage
+
+Ninguna. No hay `SimpleCov`/`.simplecov` ni umbral declarado en el repo (verificado: sin `SimpleCov` en `spec/` ni en `Gemfile.lock`).
+
+### e. Gaps de cobertura (narrado)
+
+> Cobertura declarada — qué flujos de negocio están ejercitados y cuáles no. No es el % de líneas (no hay SimpleCov, §d).
+
+**Cubierto (unit, con mocks):**
+- Mapeo de errores HTTP → excepción: `error_handler_spec` (subset de status verificado: 200, 404, 429, 500 — no los 14).
+- Modelos con métodos propios: `service` (incl. lógica de update/version), `node`, `task`, `container` (start/stop), `network`, `base` (accessors dinámicos, `assign_attributes`/`Spec` merge).
+- CRUD genérico de `config`, `secret`, `volume`: vía `shared_crud_spec` (`it_behaves_like "a crud resource"`) — no tienen spec dedicado pero **sí** están cubiertos (create/find/destroy). `image` salió del CRUD genérico (su `create` era un pull) → tiene spec propio (abajo).
+- `image`: `image_spec` (dedicado) — `Image.pull` (stream NDJSON, extracción de digest del frame `Digest:`, error tipado ante `error`/`errorDetail`, forma polimórfica del body) + `Deletable` y listado.
+- Auth de registry privado: `registry_auth_spec` (helper `RegistryAuth`: exclusión mutua `registry_auth`/`registry_auth_from`, enum del `from`, traducción a header/query) + bloque registry-auth en `service_spec` (create/update, no-exposición de la credencial en logs).
+- Infra de transporte: `api_spec`, `connection_spec`, `configuration_spec`, `log_helper_spec`, los 4 middleware specs.
+- `swarm`, `system` (singletons): `swarm_spec`, `system_spec`.
+
+**Cubierto (integration, daemon real):** lifecycle de containers, services, infra (networks/volumes), system (info/version/up/df), security (config/secret create+find+destroy).
+
+**Gaps declarados:**
+- `error_handler_spec` ejercita **un subset** de los 14 status; 400/401/403/406/408/409/422/502/503/504 y el fallback genérico no tienen aserción dedicada (gap de contrato §f).
+- `Service#restart`, `Loggable#logs` — cobertura unit no confirmada por spec dedicado; verificar.
+- Path de error `Communication` (socket caído) y la política de retry idempotente: no confirmado que haya spec dedicado en `connection_spec` (verificar).
+
+### f. Contract-assessment (¿los tests ejercitan los contratos públicos?)
+
+| contrato | RFC | cubierto | nota |
+|---|---|---|---|
+| Interfaz Ruby pública | RFC-004 | parcial | model specs + `shared_crud` ejercitan `all/find/create/update/destroy/logs`; falta aserción sistemática de toda la superficie |
+| Errores públicos | RFC-020 | parcial | `error_handler_spec` cubre el mapeo status→excepción pero **solo 4 de 14 status** → contrato de errores incompletamente verificado |
+| Docker Engine API consumida | RFC-018 | sí (integration) | los specs `type: :integration` ejercitan el contrato real contra el daemon; unit lo mockea |
+
+### g. Link a incidente
+
+`unknown` — **por ausencia de fuente, no por verificación de que no existan.** No hay un tracker de incidentes vinculado a este repo ni `refs incidente/PR` en los specs o en el historial localizable; por tanto no se puede afirmar ni que haya ni que no haya tests nacidos de un incidente. No es "cero incidentes verificado". Se completará si/cuando un test de regresión se ate explícitamente al bug que previene.
+
+### h. PII / datos sensibles en fixtures
+
+**Sin PII real ni secretos reales.** Clasificación (no valores):
+
+- Nombres de recursos: generados con `random_name(prefix)` → `SecureRandom.hex(4)` (`integration_helper.rb:26`). Sintéticos.
+- `Config`/`Secret` Data en integration: literales de prueba base64 (`Base64.strict_encode64("hello world")`, `"top secret"` — `security_spec.rb`). **No** son credenciales reales; son strings de test.
+- Unit specs: payloads inline mockeados, sin datos reales.
+
+No cruza RFC-026 (no hay PII de personas ni secretos productivos en fixtures).
+
+## 3. Inferencias
+
+| afirmación | confidence | a verificar |
+|---|---|---|
+| Los specs de modelo unit mockean `Api`/`Excon` (no tocan socket) | inferred | `spec_helper` apunta a `/tmp/docker.sock` inexistente → necesariamente stubean; patrón confirmado en `skill/SKILL.md` |
+| Integration requiere daemon Swarm activo | declared | `integration_helper` usa el socket real (`DOCKER_URL` o default) |
+
+## 4. Cobertura y fronteras
+
+- **Contenido de cada test case** individual queda en el código, no acá.
+- **Niveles:** solo unit e integration; no hay system/e2e ni matriz de versiones (`Appraisals`) — Ruby único (3.4.4) en CI.
+- **Coverage real (%)** no medible desde el repo (sin tool); §d declara la ausencia, no un número.

data/docs/topology/topology.md

@@ -0,0 +1,55 @@
+# Topología — docker-swarm
+
+> meta: artefacto · RFC-006 · generado arch-structure · anclado a `15bcd21` · cobertura: dependencias runtime (`.gemspec` + `Gemfile.lock`) y mapa de contexto de la gema
+
+## 1. Resumen
+
+Gema cliente sin servidor propio. Tres dependencias runtime (`activesupport`, `activemodel`, `excon`). Se ubica entre el código Ruby consumidor y el Docker Engine API (vía socket Unix o TCP). No tiene base de datos, colas ni servicios adyacentes propios.
+
+## 2. Cuerpo
+
+### a. Dependencias
+
+Runtime declaradas en `docker-swarm.gemspec`; versiones resueltas en `Gemfile.lock`.
+
+| nombre | versión (constraint) | resuelta | rol |
+|---|---|---|---|
+| `activesupport` | `>= 6.0` | 8.1.3 | core-ext (`HashWithIndifferentAccess`, `deep_merge`, `blank?`, `demodulize`, `pluralize`) |
+| `activemodel` | `>= 6.0` | 8.1.3 | `ActiveModel::Model` (validaciones, API de atributos) en `Base` |
+| `excon` | `>= 0.80` | 1.5.0 | cliente HTTP con soporte nativo de Unix socket + stack de middlewares |
+
+Desarrollo / test (no se empaquetan): `rake ~> 13.0`, `rspec ~> 3.0`, `pry`, `rubocop-rails-omakase`.
+
+### b. Grafo de contexto
+
+```mermaid
+flowchart LR
+  Consumer["App Ruby consumidora"] -->|usa modelos| Gem["docker-swarm (gema)"]
+  Gem -->|ActiveModel / core-ext| AS["activesupport + activemodel"]
+  Gem -->|HTTP via Excon| Daemon["Docker Engine API (dockerd)"]
+  Daemon -.->|unix:///var/run/docker.sock o TCP| Gem
+```
+
+La gema es el centro: arriba la consume una app Ruby; abajo habla con el daemon Docker por Excon. `activesupport`/`activemodel` son librerías embebidas, no servicios.
+
+### c. Modos de ejecución
+
+No aplica: es una librería embebida en el proceso del consumidor (sin web/worker/cron propios). El único "modo" es el transporte hacia el daemon:
+
+| transporte | configuración | default |
+|---|---|---|
+| Unix socket | `socket_path = "unix:///var/run/docker.sock"` | sí |
+| TCP | `socket_path = "http://host:2375"` | no |
+
+## 3. Inferencias
+
+| afirmación | confidence | a verificar |
+|---|---|---|
+| `activesupport`/`activemodel` 8.1.3 son las resueltas hoy, pero el constraint `>= 6.0` admite Rails 6/7/8 | declared | `Gemfile.lock` fija 8.1.3; el `.gemspec` no pone techo |
+| La gema no abre puertos ni corre procesos propios | declared | sin `config/`, sin `bin/` server, sin Railtie/Engine |
+
+## 4. Cobertura y fronteras
+
+- **Dependencias transitivas:** las de `activesupport` (concurrent-ruby, i18n, tzinfo, etc.) y `excon` (logger) están en `Gemfile.lock` pero no son edges del repo → fuera del grafo de contexto.
+- **El daemon Docker** es la única dependencia externa de runtime real; su contrato consumido se detalla en [`docs/consumed/docker-engine-api.md`](../consumed/docker-engine-api.md).
+- **Arquitectura upstream** (cómo está desplegado el cluster Swarm que la gema administra) es del operador, no del repo → fuera de alcance.

data/lib/docker_swarm/api.rb

@@ -66,19 +66,23 @@ module DockerSwarm
       images: {
         index: { method: :get, path: "images/json" },
         show: { method: :get, path: "images/%<id>s/json" },
-        create: { method: :post, path: "images/create?fromImage=%<id>s" },
+        pull: { method: :post, path: "images/create" },
         destroy: { method: :delete, path: "images/%<id>s" }
       }
     }.freeze
 
-    def self.request(action:, arguments: {}, query_params: {}, payload: nil)
+    def self.request(action:, arguments: {}, query_params: {}, payload: nil, headers: {})
       path = format(action[:path], arguments)
-      DockerSwarm.request(
+      options = {
         method: action[:method],
         path: path,
         query: query_params,
         body: payload
-      )
+      }
+      # Solo forwardeamos headers cuando hay: sin ellos, la request queda
+      # idéntica a la actual (no pisamos los headers por defecto de Excon).
+      options[:headers] = headers if headers && !headers.empty?
+      DockerSwarm.request(**options)
     end
   end
 end

data/lib/docker_swarm/concerns/creatable.rb

@@ -6,26 +6,52 @@ module DockerSwarm
       extend ActiveSupport::Concern
 
       class_methods do
-        def create(attributes = {})
-          resource = new(attributes)
-          resource.save
+        # @param attributes [Hash] atributos Docker (hash posicional braceado)
+        # @param opts [Hash] keywords: atributos sueltos históricos + opción reservada
+        #   +registry_auth+ (credencial para X-Registry-Auth). El resto se pliega como atributos.
+        def create(attributes = {}, **opts)
+          registry_auth = opts.delete(:registry_auth)
+          resource = new(attributes.merge(opts))
+          resource.save(registry_auth: registry_auth)
           resource
         end
+
+        # Atributos que el Engine toma por **query string** en el +create+, no en el body.
+        # Un atributo declarado acá viaja en la URL y se excluye del payload: mandarlo en
+        # el body no le da error a Docker, lo **descarta en silencio**.
+        # Override en el modelo que lo necesite (p. ej. +name+ en {DockerSwarm::Container}).
+        # @return [Array<String>] nombres de atributo
+        def create_query_params
+          [].freeze
+        end
       end
 
-      def save
+      # @param registry_auth [String, nil] credencial opaca para el header X-Registry-Auth
+      def save(registry_auth: nil)
         return false unless valid?
-        return update if persisted?
+        return update(registry_auth: registry_auth) if persisted?
 
+        headers, = RegistryAuth.resolve(registry_auth: registry_auth)
         response = Api.request(
           action: self.class.routes[:create],
-          payload: payload_for_docker
+          query_params: query_params_for_docker,
+          payload: payload_for_docker.except(*self.class.create_query_params),
+          headers: headers
         )
 
         self.ID = response["ID"] || response["Id"] || response["Name"]
         reload
         true
       end
+
+      # Los +create_query_params+ que este recurso tiene seteados, listos para la URL.
+      # @return [Hash{Symbol => Object}] vacío si el modelo no declara ninguno
+      def query_params_for_docker
+        keys = self.class.create_query_params
+        return {} if keys.empty?
+
+        attributes.slice(*keys).compact.symbolize_keys
+      end
     end
   end
 end

data/lib/docker_swarm/concerns/updatable.rb

@@ -5,16 +5,27 @@ module DockerSwarm
     module Updatable
       extend ActiveSupport::Concern
 
-      def update(new_attributes = {})
+      # @param new_attributes [Hash] atributos Docker (hash posicional braceado)
+      # @param opts [Hash] keywords: atributos sueltos históricos + opciones reservadas
+      #   +registry_auth+ (header X-Registry-Auth) / +registry_auth_from+ (query registryAuthFrom,
+      #   excluyente con registry_auth). El resto se pliega como atributos.
+      def update(new_attributes = {}, **opts)
+        registry_auth = opts.delete(:registry_auth)
+        registry_auth_from = opts.delete(:registry_auth_from)
+        # Valida (excluyente + enum) y resuelve los canales ANTES de mutar el objeto.
+        headers, auth_query = RegistryAuth.resolve(registry_auth: registry_auth, registry_auth_from: registry_auth_from)
+
         current_version = self.Version&.dig("Index")
-        assign_attributes(new_attributes) if new_attributes.present?
+        attributes = new_attributes.merge(opts)
+        assign_attributes(attributes) if attributes.present?
         return false unless valid?
 
         Api.request(
           action: self.class.routes[:update],
           arguments: { id: self.ID },
-          query_params: { version: current_version },
-          payload: payload_for_docker
+          query_params: { version: current_version }.merge(auth_query),
+          payload: payload_for_docker,
+          headers: headers
         )
 
         true