docker-swarm 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61bc38a1b8f94704857812a859abbe425f57a63130655bcbaf7938f5621ad09a
-  data.tar.gz: 1b824044722bc3a3c840889b5fef843aa6eafd25576ea25811ac8ee8e688d4e3
+  metadata.gz: 824016bc8286430e75b85e1daa74f5fa30039667230585bcd548ac76afacd1da
+  data.tar.gz: c8d56047e0e282aa35dcdd3998780f0bfcd7c5ba1be6464068bff91b99276934
 SHA512:
-  metadata.gz: bfbb5850f24f31b4e00e7da3a90e3ed73996304c757688736cc0dcbe52bba19738e0c4a9615a79f88912f984992d603546a4a46e40f4102f356b7e718b37e983
-  data.tar.gz: c3d7d6bf0e27dd190bd4dfe78a4b09436f3dada89edbf8628552a7a17d0a63a66ffb49c6c62b2e923c5f58d6cd12a584ba819e12329e13ae90ad50079e8bdc1a
+  metadata.gz: bc733a3eb22266fe1ca82dcfbc56445bf0118a8fd9c077cf697849fe15004463571c94248cd48f236d42a67d2ccbb415419e8e1a05096842bb72fec035d63fc9
+  data.tar.gz: e65002ee881d436b549918321b415b3acc224679c40690b08651ff48960f3d8c6ec3f00849ffc7830c91a8ab00d834940299e355e4225a814e231abc51a133c5

data/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+## [0.10.0] — 2026-08-05
+
+### Nuevas funcionalidades
+- **`Service.where(status: true)` puebla `ServiceStatus`** (#22). `status` es un query param **propio** de `GET /services` (Engine API ≥ v1.41), no un filtro, y hasta ahora la gema no tenía forma de mandarlo: caía en el JSON de `?filters=`, donde el Engine no lo acepta como filtro de `/services`. Con esto cada elemento del listado trae `ServiceStatus` (`RunningTasks` · `DesiredTasks` · `CompletedTasks`), que es el **único** lugar donde el Engine publica el deseado de un service en modo `global` — un replicado lo expone en `Spec.Mode.Replicated.Replicas`, pero para un global ese campo no existe. Sin `DesiredTasks` un global corriendo en 2 de 3 nodos elegibles es indistinguible de uno sano: solo se detecta el caso extremo de cero tasks — @Pslp
+  - La whitelist de query params del listado sale a `Base.index_query_params` (default `%i[all force limit since before]`, **override por modelo**), y `Service` la extiende con `:status`. Se resuelve así, y **no** subiendo `status` a `Base`, porque en `/containers/json` `status` **sí** es un filtro válido (`running`, `exited`, …): globalizarlo lo sacaría del `?filters=` y rompería `Container.where(status: "running")`. Hay un spec de regresión que lo fija.
+  - **Compatible hacia atrás:** sin pasar `status` el listado no cambia. Y **degrada en silencio**: la gema no fija `?version=`, así que en un Engine por debajo de v1.41 el parámetro se ignora sin error y `ServiceStatus` llega ausente → el consumidor tiene que tolerar `nil`, no hay señal de "no soportado".
+  - **Trampa del consumidor:** en un service `global` recién creado `DesiredTasks` vale **0** — el Engine publica los contadores antes de evaluar los nodos elegibles y lo completa ~1s después (medido contra un Engine `1.54`). En esa ventana `RunningTasks == DesiredTasks == 0`, así que comparar los dos números para decidir salud miente; `DesiredTasks.positive?` va como precondición. Documentado en `docs/consumed/` y `skill/SKILL.md`.
+
+## [0.9.0] — 2026-08-03
+
+### Nuevas funcionalidades
+- `Container` pasa a incluir `Concerns::Creatable`: la gema ya puede **crear** containers, no solo operar los existentes. El nombre viaja por **query string** (`POST /containers/create?name=`), que es donde el Engine lo espera — en el body lo descarta en silencio y responde `201`, dejando el container con nombre aleatorio. `Concerns::Creatable` gana `create_query_params` (default `[]`, override por modelo; `Container` declara `%w[name]`) y `query_params_for_docker`; `save` los manda en la URL y los excluye del payload. Implementa ADR-025 cláusula 1 — @gedera
+
+### Breaking changes
+- **`logs` devuelve texto demultiplexado.** Sin TTY el Engine enmarca cada fragmento con 8 bytes de cabecera (tipo de stream · relleno · tamaño big-endian); el nuevo `Middleware::LogStreamDemuxer` los saca, así que `Loggable#logs` entrega texto limpio en `Container`, `Service` y `Task`. **Cambia el valor de retorno** para cualquier consumidor que hoy reciba el body crudo. Un stream sin framing (TTY) pasa intacto. Implementa ADR-025 cláusula 3 — @gedera
+  - El dispatch **no** se decide solo por `Content-Type`: `application/vnd.docker.multiplexed-stream` existe desde la **API v1.42**, y antes un stream multiplexado viajaba igual como `application/vnd.docker.raw-stream`. Como la gema no fija `?version=`, un Engine que tope en v1.41 devuelve `raw-stream` **con** framing. Ante `raw-stream` el middleware valida la **forma del frame** y solo demultiplexa si la cadena cierra de punta a punta; ante cualquier inconsistencia devuelve el body intacto. Registrado en **ADR-027**, que corrige un dato de apoyo del §Alternativas de ADR-025 **sin** superseder su Decisión.
+
+### Seguridad
+- **`LogHelper.sanitize` redacta los secretos que viajan como `"CLAVE=VALOR"` en `Env`** (#24). Antes redactaba solo por **clave de hash**: un String caía al `else` y pasaba intacto, y el `Env` de un `ContainerSpec` es un **array de strings** `"CLAVE=VALOR"` donde el nombre del secreto vive *dentro* del elemento. Como `"Env"` tampoco matchea `SENSITIVE_KEYS`, el valor de todo secreto pasado por variable de entorno **se logueaba entero en `request_success` — camino feliz, nivel INFO** — en cada create/update de un service. Se agrega `redact_kv_string` y una rama `when String`: si la parte izquierda matchea `SENSITIVE_KEYS` se reemplaza el valor y **se conserva el nombre** (saber qué secreto apareció es diagnóstico útil; su valor no). El regex usa `[^=]+` a la izquierda para no partir en un `=` del valor (base64, URLs) y `/m` para valores multilínea. Afecta a **todas** las versiones anteriores — @Pslp
+  - **Hueco declarado, no cubierto por este fix:** `private_key` **no está** en `SENSITIVE_KEYS`, así que un PEM con ese nombre sigue saliendo en claro (hay un spec que lo fija como comportamiento conocido). Ampliar la lista va aparte: cambia la redacción para todos los consumidores.
+
+### Otros cambios
+- `spec.homepage` del gemspec pasa a `https://github.com/sequre/docker-swarm` (#27): el repo se transfirió de la cuenta personal `gedera` a la org `sequre`. De ahí derivan los cuatro metadata URIs (`source_code_uri`, `changelog_uri`, `bug_tracker_uri`, `documentation_uri`), así que desde esta versión apuntan a la ubicación nueva. Las versiones ya publicadas conservan la URL anterior — las salva el redirect de GitHub — @gedera
+
 ## [0.8.0] — 2026-07-22
 
 ### Nuevas funcionalidades

data/README.md

@@ -43,7 +43,7 @@ Documentación normada (RFC-001) por capa:
 |---|---|---|
 | Datos | — | `n/a` (gema sin DB) |
 | Glosario | [`docs/glossary/glossary.md`](docs/glossary/glossary.md) | completo (primitivas + arquitectura interna) |
-| Comportamiento | [`docs/behavior/behavior.md`](docs/behavior/behavior.md) | backfill on-demand (8 flujos) |
+| Comportamiento | [`docs/behavior/behavior.md`](docs/behavior/behavior.md) | backfill on-demand + incremental (12 flujos) |
 | Configuración | [`docs/config/configuracion.md`](docs/config/configuracion.md) | inventario base (7 opciones, sin env vars) |
 | Interfaz | [`docs/interface/interface.md`](docs/interface/interface.md) | API Ruby pública (11 modelos + Base + concerns) |
 | Topología | [`docs/topology/topology.md`](docs/topology/topology.md) | 3 deps runtime + grafo de contexto |

data/docs/behavior/behavior.md

@@ -1,6 +1,6 @@
 # Comportamiento — docker-swarm
 
-> meta: artefacto · RFC-007 · generado dev-enrich · anclado a `29856f1` · cobertura: 10 flujos load-bearing (8 backfill inicial + 2 nuevos: auth de registry privado, `Image.pull` síncrono)
+> meta: artefacto · RFC-007 · generado dev-enrich · anclado a `v0.10.0` · cobertura: 12 flujos load-bearing (8 backfill inicial + 4 nuevos: auth de registry privado, `Image.pull` síncrono, `Container.create`, partición query params/filters del listado)
 
 ## 1. Resumen
 
@@ -8,7 +8,7 @@ Flujos de ejecución load-bearing de `docker-swarm`: cómo se materializan en ru
 
 ## 2. Cobertura declarada
 
-### Documentados (8)
+### Documentados (12)
 
 1. `Service.create` + reload
 2. `Service.update` con `Version.Index`
@@ -20,12 +20,13 @@ Flujos de ejecución load-bearing de `docker-swarm`: cómo se materializan en ru
 8. `Loggable#logs` streaming
 9. Auth de registry privado (`RegistryAuth.resolve` → `X-Registry-Auth` / `registryAuthFrom`)
 10. `Image.pull` síncrono (stream NDJSON → error tipado → resultado explícito)
+11. `Container.create` con nombre por query string (`create_query_params`)
+12. `Model.where` — partición query params propios vs. `?filters=` (`index_query_params`)
 
 ### 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.
-- `Container.create` — **no implementado** en F1 (intencional, ver glossary).
 
 ## 3. Flujos
 
@@ -212,26 +213,38 @@ Mismo patrón para `stop`. POST sin body → no se reintenta automáticamente (
 
 ### 3.8 `Loggable#logs` streaming
 
-Obtención de logs raw para Service/Task/Container.
+Obtención de logs para Service/Task/Container, ya demultiplexados.
 
 ```mermaid
 sequenceDiagram
     actor Caller
     participant Model as Service/Task/Container
     participant Api
+    participant Demux as LogStreamDemuxer
     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
+    Docker-->>Demux: 200 stream + Content-Type
+    alt cadena de frames cierra de punta a punta
+        Demux->>Demux: saca 8 bytes de cabecera por frame, concatena en orden
+    else body sin framing (TTY) o inconsistente
+        Demux->>Demux: deja el body intacto
+    end
+    Demux-->>Api: texto limpio
+    Api-->>Model: 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.
+- El body no se parsea como JSON (`ResponseJSONParser` lo respeta porque el Content-Type no es `application/json`).
+- **El demux vive en un middleware, no en `Loggable`:** `Connection#request` devuelve `response.body` y descarta los headers, así que aguas abajo ya no hay `Content-Type` con el que decidir (ADR-025 cláusula 3).
+- **`raw-stream` no implica TTY.** Ese `Content-Type` era el único que existía antes de la API v1.42, y la gema no fija `?version=` → un Engine 20.10 devuelve `raw-stream` con framing. El middleware decide por la forma del frame, no por el header (detalle y cita del changelog en [`docs/consumed/docker-engine-api.md`](../consumed/docker-engine-api.md) §b).
+- **Desviación de ADR-025, acotada.** La **Decisión** normativa (`ADR-025:130-131` — *"un middleware que decide por `Content-Type`"*) **se cumple**: el middleware corta si el header falta o no es uno de los dos. Lo que la implementación contradice es el **rationale de §Alternativas** (`ADR-025:106-107`), que da por sentado que `raw-stream` implica TTY. Ese dato de apoyo es falso para Engines que topan en la API v1.41. Asentar la corrección en el reino queda **pendiente**.
+- **El demux limpia los frames, no separa señal de ruido.** `stdout` y `stderr` siguen intercalados en un solo String: quien necesite un dato puntual tiene que delimitarlo en origen.
+- **Un frame partido entre chunks no se reensambla:** el demux es todo-o-nada, así que devuelve el body **intacto** en vez de texto a medias. El comportamiento está definido y cubierto por spec — los cuatro casos que pide `ADR-025:196-198` (cadena de frames, varios en un chunk, tamaño/cola truncados, TTY sin framing) están en `spec/docker/swarm/middleware/log_stream_demuxer_spec.rb`.
+- `follow: 1` mantiene la conexión abierta — el caller debe manejar el stream/timeout. `[inferred]` Con `follow` el body no llega completo, así que el demux no aplica por diseño; no está ejercitado por spec ni contemplado en ADR-025 — es extrapolación de esta capa, no una limitación declarada por la ADR.
 
 ### 3.9 Auth de registry privado (`X-Registry-Auth` / `registryAuthFrom`)
 
@@ -287,12 +300,67 @@ sequenceDiagram
 - El digest sale del frame `Digest: sha256:...` (el stream de pull **no** trae campo `aux` — verificado contra Docker 29.5.3), escaneando desde el final.
 - Es un `POST` → **no** entra en la política de retries (ver flujo 3.5).
 
+### 3.11 `Container.create` con nombre por query string
+
+El Engine toma el nombre del container por query string. En el body lo **descarta en silencio** y responde `201` igual: el container nace con nombre aleatorio, y una lógica de adopción por nombre determinista no lo encuentra → el reintento duplica en vez de adoptar (ADR-025 cláusula 1).
+
+```mermaid
+sequenceDiagram
+    actor Caller
+    participant Container as DockerSwarm::Container
+    participant Api
+    participant Docker
+
+    Caller->>Container: Container.create(name: "acs-seed-helper", Image:, Cmd:)
+    Container->>Container: valid?
+    Container->>Container: query_params_for_docker → { name: "acs-seed-helper" }
+    Container->>Container: payload_for_docker.except("name")
+    Container->>Api: request(:create, query_params:, payload:)
+    Api->>Docker: POST /containers/create?name=acs-seed-helper
+    Docker-->>Api: 201 { Id: "abc" }
+    Api-->>Container: { Id: "abc" }
+    Container->>Container: self.ID = "abc" → reload
+    Container-->>Caller: instancia hidratada
+```
+
+**Notas load-bearing:**
+- El split lo declara el modelo con `.create_query_params` (`%w[name]` en `Container`); el default del concern es `[]`, así que los demás modelos Creatable no cambian de comportamiento.
+- **El atributo se excluye del payload**, no se duplica: mandarlo en los dos lados no da error pero deja el body con una clave que Docker ignora.
+- Hereda el flujo §3.1: `valid?` antes del POST, `reload` después, y **sin retry** por ser `POST` (§3.5). Si el `create` falla por `Communication`, el caller decide — con nombre determinista puede adoptar el existente en el reintento.
+
+### 3.12 `Model.where` — partición query params propios vs. `?filters=`
+
+El Engine parte los parámetros de un listado en dos grupos, y la gema tiene que decidir a cuál va cada clave **antes** de armar la URL. `Base.index_query_params` es esa declaración; todo lo que no esté ahí se serializa dentro del JSON de `?filters=`.
+
+La trampa: un query param propio que el modelo no declaró **no llega**. Viaja dentro de `filters`, donde el Engine lo rechaza o lo ignora según el recurso — no hay error que diga "esa clave iba en la URL".
+
+```mermaid
+flowchart TD
+    A["Model.where(status: true, name: 'web')"] --> B["_fetch_all"]
+    B --> C{"clave ∈ index_query_params?"}
+    C -->|sí| D["query params propios<br/>{ status: true }"]
+    C -->|no| E["docker_filters<br/>{ name: 'web' }"]
+    E --> F["downcase claves + Array(valor)<br/>→ JSON"]
+    D --> G["query = { status: true,<br/>filters: '{\"name\":[\"web\"]}' }"]
+    F --> G
+    G --> H["GET /services?status=true&filters=..."]
+    H --> I["array de Hash → instancias"]
+```
+
+**Notas load-bearing:**
+- **La lista es por modelo, no global.** `Base` declara `%i[all force limit since before]`; `Service` la extiende con `:status`. Deliberadamente no se generaliza: `status` es query param propio en `/services` pero **filtro válido** en `/containers/json` (`running`, `exited`, …), así que subirlo a `Base` lo sacaría del `?filters=` donde containers lo necesita. Hay un spec de regresión que lo fija.
+- **`Service.where(status: true)` es lo que habilita leer `ServiceStatus`** (`RunningTasks` · `DesiredTasks` · `CompletedTasks`), única superficie donde el Engine publica el **deseado** de un service en modo `global` — un replicado lo tiene en `Spec.Mode.Replicated.Replicas`, un global no tiene ese campo. Sin eso, un global corriendo en 2 de 3 nodos elegibles es indistinguible de uno sano: se ven las tasks que corren, no contra qué comparar.
+- **Requiere API ≥ v1.41 y degrada en silencio.** La gema no fija `?version=` (§3.5 / [`docs/consumed/`](../consumed/docker-engine-api.md)); en un Engine anterior el parámetro se ignora sin error y `ServiceStatus` llega ausente → el consumidor tolera `nil`, no hay señal de "no soportado".
+- **`DesiredTasks` arranca en 0 en un `global` recién creado** y el Engine lo completa después de evaluar los nodos (~1s, medido). En esa ventana `RunningTasks == DesiredTasks == 0`: el deseado no está calculado, así que comparar los dos números miente. Precondición de salud = `DesiredTasks.positive?`. Detalle en [`docs/consumed/`](../consumed/docker-engine-api.md).
+- **Las claves se matchean como símbolos.** `where("status" => true)` cae en `docker_filters` (`slice(:status)` no matchea la string). Comportamiento preexistente y común a todos los query params del listado, no introducido por `:status`.
+- Sin filtros no hay query: `all` manda `query_params: {}` — el listado por default no cambió.
+
 ## 4. Cobertura y fronteras
 
-- **Cobertura (RFC-007 backfill on-demand + incremental):** 8 flujos load-bearing en el backfill inicial + 2 agregados con el soporte de auth de registry privado (auth de registry privado, `Image.pull` síncrono) = 10. Esta gema es chica; el backfill completo era factible y se hizo, y a partir de ahí se acreta por PR.
+- **Cobertura (RFC-007 backfill on-demand + incremental):** 8 flujos load-bearing en el backfill inicial + 2 agregados con el soporte de auth de registry privado (auth de registry privado, `Image.pull` síncrono) + 1 con el `create` de containers + 1 con la partición query params/filters del listado = 12. Esta gema es chica; el backfill completo era factible y se hizo, y a partir de ahí se acreta por PR.
 - **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).
+  - Nada pendiente por este motivo. (Hasta el 2026-08-03 esta línea decía que la gema no implementaba `X-Registry-Auth` y citaba `Image.create`; las dos cosas quedaron obsoletas — la auth de registry está documentada en §3.9 e `Image.create` fue retirado.)
 - **Cadencia incremental a partir de acá:** sólo se diagrama un flujo cuando un PR lo toca o agrega. No barrido retroactivo de legacy.

data/docs/consumed/docker-engine-api.md

@@ -1,6 +1,6 @@
 # Dependencias consumidas — docker-swarm
 
-> meta: artefacto · RFC-018 · generado arch-structure + enriquecido arch-enrich · anclado a `29856f1` · cobertura: superficie del Docker Engine API consumida por la gema (`api.rb` ENDPOINTS + `connection.rb`); §c/§e enriquecidas 1/1
+> meta: artefacto · RFC-018 · generado arch-structure + enriquecido arch-enrich · anclado a `v0.10.0` · cobertura: superficie del Docker Engine API consumida por la gema (`api.rb` ENDPOINTS + `connection.rb`); §c/§e enriquecidas 1/1
 
 ## 1. Resumen
 
@@ -19,7 +19,7 @@ La gema consume **una** dependencia externa: el **Docker Engine API** (HTTP REST
 | transporte | HTTP/REST sobre Unix socket (`unix:///var/run/docker.sock`, default) o TCP (`http://host:2375`) |
 | cliente nuestro | `DockerSwarm::Connection` (Excon) + `DockerSwarm::Api` (`api.rb`) |
 | auth | ninguna por default (socket local). TCP/TLS → fuera de alcance del cliente (no inyecta credenciales; 401 si el daemon las exige) |
-| versión de API | v1.41 (referencia en los `@see` de los modelos; no se negocia explícitamente) |
+| versión de API | v1.41 (referencia en los `@see` de los modelos; no se negocia explícitamente). **La gema no fija `?version=`** → el daemon sirve su versión **máxima**, así que la versión efectiva la decide cada host. Piso relevante: un Engine 20.10 topa en **v1.41**. Techo del parque: `unknown` (no derivable de este repo). Consecuencia en los logs: ver §b |
 | ancla | doc oficial: <https://docs.docker.com/engine/api/v1.41/> |
 
 #### b. Operaciones consumidas
@@ -38,22 +38,22 @@ Subset que la gema invoca, derivado de `Api::ENDPOINTS` (`api.rb:5-72`). `destin
 | nodes | update | `POST nodes/%<id>s/update` | `?version=` + payload / — |
 | nodes | destroy | `DELETE nodes/%<id>s` | — / — |
 | tasks | index / show | `GET tasks`, `GET tasks/%<id>s` | `?filters=` / array \| Hash |
-| tasks | logs | `GET tasks/%<id>s/logs` | `?stdout/stderr/...` / stream raw |
-| services | index / show | `GET services`, `GET services/%<id>s` | `?filters=` / array \| Hash |
+| tasks | logs | `GET tasks/%<id>s/logs` | `?stdout/stderr/...` / stream multiplexado (demux en el cliente) |
+| services | index / show | `GET services`, `GET services/%<id>s` | `?filters=` + `?status=` (query propio, **no** filtro; ≥ v1.41) / array \| Hash; con `?status=true` cada elemento trae `ServiceStatus` |
 | services | create | `POST services/create` | payload (Spec aplanado) + header `X-Registry-Auth` (opcional, registry privado) / `{ID}` |
 | services | update | `POST services/%<id>s/update` | `?version=` (+ `?registryAuthFrom=` opcional: `spec`\|`previous-spec`) + payload + header `X-Registry-Auth` (opcional; excluyente con `registryAuthFrom`) / — |
 | services | destroy | `DELETE services/%<id>s` | — / — |
-| services | logs | `GET services/%<id>s/logs` | `?stdout/stderr/...` / stream raw |
+| services | logs | `GET services/%<id>s/logs` | `?stdout/stderr/...` / stream multiplexado (demux en el cliente) |
 | configs | index / show / create / destroy | `GET configs`, `GET configs/%<id>s`, `POST configs/create`, `DELETE configs/%<id>s` | payload en create / `{ID}` |
 | secrets | index / show / create / destroy | `GET secrets`, `GET secrets/%<id>s`, `POST secrets/create`, `DELETE secrets/%<id>s` | payload en create (`Data` filtrado en logs) / `{ID}` |
 | networks | index / show / create / update / destroy | `GET/POST networks...`, `POST networks/%<id>s/update`, `DELETE networks/%<id>s` | payload / `{ID}` |
 | volumes | index / show / create / destroy | `GET volumes`, `GET volumes/%<id>s`, `POST volumes/create`, `DELETE volumes/%<id>s` | payload / respuesta wrapped en `Volumes` |
 | containers | index | `GET containers/json` | `?filters=` / array |
 | containers | show | `GET containers/%<id>s/json` | — / Hash |
-| containers | create | `POST containers/create` | payload / `{Id}` |
+| containers | create | `POST containers/create` | `?name=` (query, NO en el body) + payload / `{Id}` |
 | containers | start / stop | `POST containers/%<id>s/start`, `POST containers/%<id>s/stop` | — / — |
 | containers | destroy | `DELETE containers/%<id>s` | — / — |
-| containers | logs | `GET containers/%<id>s/logs` | `?stdout/stderr/...` / stream raw |
+| containers | logs | `GET containers/%<id>s/logs` | `?stdout/stderr/...` / stream multiplexado (demux en el cliente) |
 | images | index | `GET images/json` | — / array |
 | images | show | `GET images/%<id>s/json` | — / Hash |
 | images | pull | `POST images/create?fromImage=<ref>` | header `X-Registry-Auth` (opcional, registry privado) / stream NDJSON de progreso |
@@ -61,6 +61,32 @@ Subset que la gema invoca, derivado de `Api::ENDPOINTS` (`api.rb:5-72`). `destin
 
 Serialización: request body no-String → JSON (`Content-Type: application/json`) vía `Middleware::RequestEncoder`; response `application/json` → `HashWithIndifferentAccess` recursivo vía `Middleware::ResponseJSONParser`.
 
+**Query params propios vs. `?filters=` (listados).** El Engine parte los parámetros de un listado en dos: query params propios de la ruta (`?limit=`, `?all=`, `?status=`) y el JSON de `?filters=`. La gema declara los primeros en `Base.index_query_params` (override por modelo); **todo lo demás se serializa como filtro**. Un query param propio no declarado ahí no llega nunca: viaja dentro del JSON de `filters` y el Engine lo rechaza (si valida la clave) o lo ignora.
+
+Los nombres **no** son globales — el mismo `status` es query param propio en `/services` y filtro válido en `/containers/json` (`running`, `exited`, …). De ahí que la lista sea por modelo y no una whitelist única.
+
+**`?status=true` en `/services`** (API ≥ v1.41) agrega a cada elemento:
+
+```json
+{ "ServiceStatus": { "RunningTasks": 2, "DesiredTasks": 3, "CompletedTasks": 0 } }
+```
+
+Es la **única** superficie donde el Engine publica el deseado de un service en modo `global`: un replicado lo expone en `Spec.Mode.Replicated.Replicas`, pero para un global ese campo no existe (el deseado es "una task por nodo elegible"). Sin `DesiredTasks` no hay número contra el cual comparar las tasks que corren.
+
+Como la gema no fija `?version=`, la versión efectiva la decide el host (ver arriba): en un Engine por debajo de v1.41 el parámetro se **ignora sin error** y `ServiceStatus` llega ausente. El consumidor tiene que tolerar `nil` — no hay señal de "no soportado".
+
+**`DesiredTasks: 0` no significa "sin nodos elegibles".** En un service `global` recién creado el Engine publica el objeto con los tres contadores en **0** y recién después evalúa los nodos (medido contra un Engine `1.54`, swarm de un nodo: `DesiredTasks` pasa de 0 a 1 en ~1s). O sea que hay una ventana en la que `RunningTasks == DesiredTasks == 0` — un consumidor que compare los dos números lee "sano" (0 de 0) o "degradado total" según cómo ordene la comparación, y en ninguno de los dos casos es cierto: el deseado todavía no está calculado. Para decidir salud hace falta `DesiredTasks.positive?` como precondición, no como resultado.
+
+**Streams de logs (`containers`/`services`/`tasks` → `logs`).** Sin TTY el Engine multiplexa: 8 bytes de cabecera por frame (1 tipo de stream · 3 de relleno en cero · 4 de tamaño big-endian). `Middleware::LogStreamDemuxer` los saca, así que `Loggable#logs` entrega texto limpio.
+
+El `Content-Type` **no alcanza** para decidir. `application/vnd.docker.multiplexed-stream` existe **desde la API v1.42**; su entrada de changelog dice, textual:
+
+> `GET /containers/{id}/attach`, `GET /exec/{id}/start`, `GET /containers/{id}/logs` `GET /services/{id}/logs` and `GET /tasks/{id}/logs` now set Content-Type header to `application/vnd.docker.multiplexed-stream` when a multiplexed stdout/stderr stream is sent to client, `application/vnd.docker.raw-stream` otherwise.
+
+Antes de v1.42 ese valor no existía y un stream multiplexado viajaba igual como `application/vnd.docker.raw-stream`. Como la gema no fija `?version=`, un Engine 20.10 (tope v1.41) devuelve `raw-stream` **con** framing. Por eso el middleware, ante `raw-stream`, decide por la **forma del frame** —recorre el body entero y solo demultiplexa si la cadena de frames cierra de punta a punta— en vez de confiar en el header. Ante cualquier inconsistencia deja el body intacto.
+
+> Anclaje: <https://docs.docker.com/reference/api/engine/version-history/> (entrada de v1.42).
+
 #### d. Errores del proveedor → excepción nuestra
 
 El daemon responde con status HTTP; `Middleware::ErrorHandler` los mapea a la jerarquía `DockerSwarm::Error`. La tabla completa status→excepción está en [`docs/errors/errors.md`](../errors/errors.md) §b (este artefacto **referencia**, no la redefine).

data/docs/glossary/glossary.md

@@ -1,6 +1,6 @@
 # Glosario — docker-swarm
 
-> meta: artefacto · RFC-009 · generado dev-enrich · anclado a `8f2e1f7` · 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
 
@@ -25,7 +25,7 @@ Unidad de ejecución de un Service en un Node específico. Read-only: las tasks
 
 ## 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
@@ -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

@@ -1,6 +1,6 @@
 # Interfaz — docker-swarm
 
-> meta: artefacto · RFC-004 · generado arch-structure · anclado a `29856f1` · cobertura: API Ruby pública de la gema (`lib/docker_swarm/**`); símbolos internos marcados en §4
+> meta: artefacto · RFC-004 · generado arch-structure · anclado a `v0.10.0` · cobertura: API Ruby pública de la gema (`lib/docker_swarm/**`); símbolos internos marcados en §4
 
 ## 1. Resumen
 
@@ -15,7 +15,7 @@ Proyección RBS-conceptual: `símbolo · tipo · nota` (raíz → profundidad
 | símbolo | tipo | nota |
 |---|---|---|
 | `DockerSwarm` | módulo | namespace raíz |
-| `DockerSwarm::VERSION` | constante | `"0.8.0"` (`version.rb`) |
+| `DockerSwarm::VERSION` | constante | `"0.10.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) |
@@ -48,6 +48,7 @@ Inventario completo de opciones: [`docs/config/configuracion.md`](../config/conf
 | `.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` |
+| `.index_query_params` | método de clase | `%i[all force limit since before]` por default; override por modelo (`+ :status` en `Service`). Claves que viajan como **query params propios** del listado; **todo lo no declarado se serializa dentro del JSON de `?filters=`** — si tampoco es filtro válido del recurso, el Engine lo rechaza o lo ignora |
 | `#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 |
@@ -63,21 +64,23 @@ Inventario completo de opciones: [`docs/config/configuracion.md`](../config/conf
 | 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 |
+| `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 el stream raw |
+| `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::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; `.index_query_params` agrega `:status` → `where(status: true)` puebla `ServiceStatus` (`RunningTasks`/`DesiredTasks`/`CompletedTasks`), único lugar donde el Engine publica el deseado de un service `global` |
 | `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 | Deletable, Loggable; `#start`, `#stop` (sin `create`: gap intencional) |
+| `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) |
@@ -99,7 +102,8 @@ Inventario completo de opciones: [`docs/config/configuracion.md`](../config/conf
 | `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, ResponseJSONParser, ErrorHandler}` | clases | middlewares Excon; públicos por require pero de uso interno (ver §4) |
+| `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
 

data/docs/release/release.md

@@ -1,6 +1,6 @@
 # Release — docker-swarm
 
-> meta: artefacto · RFC-014 · generado arch-structure + enriquecido arch-enrich · anclado a `cccfe63` · cobertura: §a estructura completa (versión · changelog · build-trigger · patrón); §b enrich completa (deploy · rollback · ambientes · dueño)
+> meta: artefacto · RFC-014 · generado arch-structure + enriquecido arch-enrich · anclado a `v0.10.0` · cobertura: §a estructura completa (versión · changelog · build-trigger · patrón); §b enrich completa (deploy · rollback · ambientes · dueño)
 
 ## 1. Resumen
 
@@ -12,7 +12,7 @@ Gema Ruby publicada en RubyGems. Release por **tag `v*`**: el push del tag dispa
 
 | campo | valor | fuente |
 |---|---|---|
-| versión actual | `0.7.2` | `lib/docker_swarm/version.rb` (`DockerSwarm::VERSION`) |
+| versión actual | `0.10.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` |

data/docs/test/testing.md

@@ -1,6 +1,6 @@
 # Test — docker-swarm
 
-> meta: artefacto · RFC-013 · generado arch-structure + enriquecido arch-enrich · anclado a `8f2e1f7` · cobertura: estructura de la suite (`spec/`, `.github/workflows/main.yml`); §e enriquecida, §f enriquecida, §g `unknown` (sin incidentes registrados), §h enriquecida
+> meta: artefacto · RFC-013 · generado arch-structure + enriquecido arch-enrich · anclado a `v0.10.0` · cobertura: estructura de la suite (`spec/`, `.github/workflows/main.yml`); §e enriquecida, §f enriquecida, §g `unknown` (sin incidentes registrados), §h enriquecida
 
 ## 1. Resumen
 
@@ -15,7 +15,7 @@ Framework: **RSpec** (`~> 3.0`). `verify_partial_doubles = true` (mocks estricto
 | 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, request_encoder, response_json_parser | 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` |
 
@@ -54,7 +54,8 @@ Ninguna. No hay `SimpleCov`/`.simplecov` ni umbral declarado en el repo (verific
 - 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 3 middleware specs.
+- Partición query params propios vs. `?filters=` del listado (`index_query_params`): `base_spec` (default, override, partición mixta), `service_spec` (`status: true` → query param; `ServiceStatus` expuesto y tolerancia a su ausencia), `container_spec` (**regresión**: `status` sigue viajando como filtro). Integration: `services_spec` verifica contra el daemon que `ServiceStatus` aparece **solo** con `status: true`, y un `context` en modo **`global`** pinnea el caso que justifica la feature — `DesiredTasks` legible donde `Spec.Mode.Replicated` no existe. Ese context es el que vuelve necesario el poll del helper `listed_with_status`: en un global el deseado arranca en 0 y el Engine lo completa después (~1s), así que la condición de corte es `DesiredTasks.positive?`, no `ServiceStatus.present?`.
+- 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).

data/lib/docker_swarm/base.rb

@@ -46,14 +46,33 @@ module DockerSwarm
         all(filters)
       end
 
+      # Claves que el Engine toma como **query params propios** del listado
+      # (`?limit=`, `?all=`, …), no como *filters*.
+      #
+      # Todo lo que NO esté declarado acá se serializa dentro del JSON de `?filters=`.
+      # Si además no es un filtro válido del recurso, el Engine lo rechaza o lo ignora:
+      # el parámetro **no llega** y no hay forma de pedirlo desde la gema.
+      #
+      # Override en el modelo que declare uno propio (p. ej. `status` en
+      # {DockerSwarm::Service}). La lista **no** se generaliza acá por comodidad: un
+      # mismo nombre puede ser query param en un recurso y filtro legítimo en otro
+      # (`status` lo es en `/containers/json`), y globalizarlo lo saca del `?filters=`
+      # donde ese otro recurso lo necesita.
+      #
+      # @return [Array<Symbol>] nombres de query param
+      def index_query_params
+        %i[all force limit since before].freeze
+      end
+
       private
 
       def _fetch_all(filters = {})
         query = {}
 
         if filters.present?
-          global_params = filters.slice(:all, :force, :limit, :since, :before)
-          docker_filters = filters.except(:all, :force, :limit, :since, :before)
+          query_keys = index_query_params
+          global_params = filters.slice(*query_keys)
+          docker_filters = filters.except(*query_keys)
 
           query = global_params
 

data/lib/docker_swarm/concerns/creatable.rb

@@ -15,6 +15,15 @@ module DockerSwarm
           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
 
       # @param registry_auth [String, nil] credencial opaca para el header X-Registry-Auth
@@ -25,7 +34,8 @@ module DockerSwarm
         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
         )
 
@@ -33,6 +43,15 @@ module DockerSwarm
         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/connection.rb

@@ -96,6 +96,7 @@ module DockerSwarm
       Excon.defaults[:middlewares] + [
         Excon::Middleware::RedirectFollower,
         Middleware::RequestEncoder,
+        Middleware::LogStreamDemuxer,
         Middleware::ResponseJSONParser,
         Middleware::ErrorHandler
       ]
@@ -105,9 +106,17 @@ module DockerSwarm
       # NO habilitamos el debug de Excon ni le pasamos el logger. El instrumentor
       # de Excon redacta solo Authorization/Proxy-Authorization, NUNCA headers de
       # autenticación custom (p. ej. X-Registry-Auth) → filtraría esa credencial.
-      # Nuestro #log_event ya loguea request/response con redacción recursiva
-      # (LogHelper.sanitize). Para wire-debug explícito y consciente del riesgo queda
-      # EXCON_DEBUG (mecanismo nativo de Excon, off por defecto).
+      #
+      # Nuestro #log_event loguea request/response pasando por
+      # {LogHelper.sanitize}, que cubre DOS formas: la clave de hash sensible
+      # (headers anidados) y el `"CLAVE=VALOR"` dentro de un String (el `Env` de
+      # un ContainerSpec, que es un array de strings). Lo que NO cubre —y hay que
+      # tenerlo presente antes de sumar un logueo nuevo— es un secreto embebido
+      # en texto libre sin la forma `CLAVE=VALOR`: ahí el nombre de la clave no
+      # aparece y no hay por dónde reconocerlo.
+      #
+      # Para wire-debug explícito y consciente del riesgo queda EXCON_DEBUG
+      # (mecanismo nativo de Excon, off por defecto).
       options = {
         middlewares: common_middlewares,
         retry_limit: 0

data/lib/docker_swarm/log_helper.rb

@@ -9,12 +9,27 @@ module DockerSwarm
     SENSITIVE_KEYS = /password|pass|passwd|secret|token|api_key|auth|\bdata\b/i.freeze
     FILTERED = "[FILTERED]"
 
-    # Redacta recursivamente los valores cuya CLAVE es sensible, a cualquier
-    # profundidad (hashes y arrays anidados). No muta la entrada: devuelve copias.
+    # Un elemento de `Env` de Docker: `"CLAVE=VALOR"`. El `[^=]+` a la izquierda
+    # evita partir en un `=` que pertenezca al valor (los valores base64 y las
+    # URLs los traen), y `/m` cubre un valor multilínea — una clave PEM pasada
+    # por variable de entorno.
+    KV_STRING = /\A([^=]+)=(.+)\z/m
+
+    # Redacta recursivamente los valores sensibles, a cualquier profundidad
+    # (hashes y arrays anidados). No muta la entrada: devuelve copias.
+    #
+    # Cubre DOS formas, porque el nombre de un secreto no siempre es una clave
+    # de hash:
     #
-    # Un header sensible puede viajar anidado (`headers: { "X-Registry-Auth" => "<cred>" }`)
-    # y el match por clave de primer nivel no lo alcanzaba — el hash interno se
-    # interpolaba entero.
+    # 1. **Clave de hash sensible** — `headers: { "X-Registry-Auth" => "<cred>" }`.
+    #    Un header sensible puede viajar anidado, y el match por clave de primer
+    #    nivel no lo alcanzaba: el hash interno se interpolaba entero.
+    # 2. **`"CLAVE=VALOR"` dentro de un String** — el `Env` de un `ContainerSpec`
+    #    es un ARRAY DE STRINGS, así que el nombre del secreto vive dentro del
+    #    elemento y no como clave. Sin esto, `Env` no matchea {SENSITIVE_KEYS},
+    #    sus elementos caen al `else`, y **el valor de todo secreto pasado por
+    #    variable de entorno se loguea entero** — en `request_success`, o sea en
+    #    el camino feliz, a nivel INFO.
     #
     # @param value [Object] hash, array o escalar
     # @return [Object] copia con los valores sensibles reemplazados por [FILTERED]
@@ -26,11 +41,30 @@ module DockerSwarm
         end
       when Array
         value.map { |v| sanitize(v) }
+      when String
+        redact_kv_string(value)
       else
         value
       end
     end
 
+    # Redacta el VALOR de un String con forma `"CLAVE=VALOR"` cuando la clave es
+    # sensible, conservando el nombre: saber QUÉ secreto apareció es diagnóstico
+    # útil, su valor no.
+    #
+    # Un String que no tiene esa forma —o cuya clave no es sensible— vuelve tal
+    # cual, así que `"RAILS_LOG_LEVEL=info"` y cualquier mensaje de error quedan
+    # intactos.
+    #
+    # @param str [String]
+    # @return [String] con el valor reemplazado por {FILTERED}, o el original
+    def self.redact_kv_string(str)
+      match = KV_STRING.match(str)
+      return str unless match && match[1].match?(SENSITIVE_KEYS)
+
+      "#{match[1]}=#{FILTERED}"
+    end
+
     # Formats a hash into a KV structured string with sensitive data masking
     # @param payload [Hash] The data to format
     # @return [String] KV formatted string

data/lib/docker_swarm/middleware/log_stream_demuxer.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module DockerSwarm
+  module Middleware
+    # Demultiplexa el stream de logs del Engine para que +Concerns::Loggable#logs+
+    # devuelva texto limpio en +Container+, +Service+ y +Task+.
+    #
+    # Sin TTY el Engine enmarca cada fragmento con 8 bytes de cabecera: 1 de tipo de
+    # stream, 3 de relleno en cero y 4 de tamaño en big-endian. Ese framing tiene que
+    # morir en un middleware y no en +Loggable+: +Connection#request+ devuelve
+    # +response.body+ y descarta los headers, así que aguas abajo ya no queda
+    # +Content-Type+ con el que decidir. Ver ADR-025 cláusula 3.
+    #
+    # @see https://docs.docker.com/engine/api/v1.41/#tag/Container/operation/ContainerAttach
+    class LogStreamDemuxer < Excon::Middleware::Base
+      # Content-Type que **afirma** el framing. Existe desde la API v1.42.
+      MULTIPLEXED_CONTENT_TYPE = "application/vnd.docker.multiplexed-stream"
+      # Content-Type ambiguo: con TTY no hay framing, pero antes de v1.42 era el único
+      # que existía y también viajaba en streams multiplexados.
+      RAW_CONTENT_TYPE = "application/vnd.docker.raw-stream"
+
+      # Tamaño de la cabecera de frame, en bytes.
+      HEADER_SIZE = 8
+      # Valores válidos del byte 0: stdin, stdout, stderr.
+      STREAM_TYPES = [ 0, 1, 2 ].freeze
+
+      def response_call(env)
+        demux!(env) if env[:response]
+
+        @stack.response_call(env)
+      end
+
+      private
+
+      def demux!(env)
+        body = env[:response][:body]
+        return unless body.is_a?(String)
+        return if body.empty?
+
+        content_type = (env[:response][:headers] || {})["Content-Type"]
+        return if content_type.nil?
+
+        # Sobre +raw-stream+ no alcanza el Content-Type para descartar el framing: la
+        # gema no fija +?version=+ (habla la versión máxima del Engine) y un nodo del
+        # parque puede topar en v1.41, donde un stream multiplexado llega igual con
+        # este Content-Type. Ahí decide la forma del frame, no el header.
+        return unless content_type.include?(MULTIPLEXED_CONTENT_TYPE) ||
+                      content_type.include?(RAW_CONTENT_TYPE)
+
+        demuxed = demux(body)
+        env[:response][:body] = demuxed unless demuxed.nil?
+      end
+
+      # Recorre el body entero como cadena de frames y concatena las cargas en orden.
+      #
+      # Es todo-o-nada a propósito: alcanza **una** inconsistencia —tipo de stream fuera
+      # de rango, relleno distinto de cero, un tamaño que se pasa del buffer, una cola
+      # suelta— para devolver +nil+ y dejar el body intacto. Un log de TTY tendría que
+      # ser una cadena perfecta de frames válidos de punta a punta para confundirse.
+      #
+      # @param body [String] el body crudo tal como vino del Engine
+      # @return [String, nil] el texto sin cabeceras, o +nil+ si el body no está enmarcado
+      def demux(body)
+        bytes = body.b
+        size = bytes.bytesize
+        offset = 0
+        out = +""
+
+        while offset < size
+          return nil if size - offset < HEADER_SIZE
+
+          stream_type, pad_a, pad_b, pad_c, length =
+            bytes.byteslice(offset, HEADER_SIZE).unpack("C4N")
+
+          return nil unless STREAM_TYPES.include?(stream_type)
+          return nil unless pad_a.zero? && pad_b.zero? && pad_c.zero?
+
+          offset += HEADER_SIZE
+          return nil if size - offset < length
+
+          out << bytes.byteslice(offset, length)
+          offset += length
+        end
+
+        out.force_encoding(Encoding::UTF_8)
+      end
+    end
+  end
+end

data/lib/docker_swarm/models/container.rb

@@ -4,9 +4,19 @@ module DockerSwarm
   # Represents a Docker Container
   # @see https://docs.docker.com/engine/api/v1.41/#tag/Container
   class Container < Base
+    include Concerns::Creatable
     include Concerns::Deletable
     include Concerns::Loggable
 
+    # +POST /containers/create+ toma el nombre por query string. En el body Docker lo
+    # **descarta en silencio** y responde +201+: el container nace con nombre aleatorio
+    # y la adopción por nombre determinista en un reintento no encuentra nada, así que
+    # el reintento duplica. Ver ADR-025 cláusula 1.
+    # @return [Array<String>]
+    def self.create_query_params
+      %w[name].freeze
+    end
+
     # Starts the container
     # @return [Boolean] true if successful
     def start

data/lib/docker_swarm/models/service.rb

@@ -9,6 +9,30 @@ module DockerSwarm
     include Concerns::Deletable
     include Concerns::Loggable
 
+    # `status` es un query param **propio** de `GET /services` (Engine API ≥ v1.41), no un
+    # filtro: con `?status=true` cada elemento del listado trae `ServiceStatus`
+    # (`RunningTasks` · `DesiredTasks` · `CompletedTasks`).
+    #
+    # Es el **único** lugar donde el Engine publica el deseado de un service en modo
+    # `global`. Un service replicado lo expone en `Spec.Mode.Replicated.Replicas`, pero
+    # para uno global ese campo no existe —el deseado es "una task por nodo elegible"—,
+    # así que sin `DesiredTasks` no hay número contra el cual comparar las tasks que
+    # corren: un global degradado *parcialmente* (2 de 3 nodos) es indistinguible de uno
+    # sano, y solo se detecta el caso extremo de cero tasks.
+    #
+    # Va acá y no en la whitelist de {DockerSwarm::Base} porque en `/containers/json`
+    # `status` **sí** es un filtro válido (`running`, `exited`, …): globalizarlo lo sacaría
+    # del `?filters=` y rompería `Container.where(status: "running")`.
+    #
+    # En un Engine por debajo de v1.41 el parámetro se ignora sin error y `ServiceStatus`
+    # llega ausente → el consumidor tiene que tolerar `nil`.
+    #
+    # @return [Array<Symbol>] Symbols (no Strings como +create_query_params+): acá se
+    #   matchea contra las claves de +filters+.
+    def self.index_query_params
+      (super + %i[status]).freeze
+    end
+
     # Restarts the service by incrementing ForceUpdate, which causes
     # Docker to recreate all tasks.
     #

data/lib/docker_swarm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DockerSwarm
-  VERSION = "0.8.0"
+  VERSION = "0.10.0"
 end

data/lib/docker_swarm.rb

@@ -40,6 +40,7 @@ require_relative "docker_swarm/log_helper"
 require_relative "docker_swarm/version"
 require_relative "docker_swarm/errors"
 require_relative "docker_swarm/middleware/request_encoder"
+require_relative "docker_swarm/middleware/log_stream_demuxer"
 require_relative "docker_swarm/middleware/response_json_parser"
 require_relative "docker_swarm/middleware/error_handler"
 require_relative "docker_swarm/connection"

data/skill/SKILL.md

@@ -10,15 +10,18 @@ description: >-
   actualizar/eliminar recursos del cluster, leer logs de services/tasks/
   containers, hacer health-check del daemon (System.up/info/df), filtrar por
   labels, pullear imágenes (incl. de registries privados vía X-Registry-Auth),
-  o capturar errores tipados de Docker (Conflict/NotFound/Communication). NO
-  activar para builds de imágenes (no implementado) o flujos que no son Swarm
-  (Docker Compose, raw containers).
+  o capturar errores tipados de Docker (Conflict/NotFound/Communication).
+  También cubre containers standalone (no Swarm): crear/correr/limpiar un
+  helper container efímero para operar datos on-host. NO activar para builds
+  de imágenes (no implementado) ni para Docker Compose (no parsea
+  `docker-compose.yml`).
 triggers:
   - "DockerSwarm::"
   - "docker-swarm gem"
   - "Docker Engine API desde Ruby"
   - "Service.create / Service.update / Service.restart"
-  - "Container.start / Container.stop"
+  - "Container.create / Container.start / Container.stop"
+  - "helper container efímero"
   - "logs de un servicio Docker"
   - "Version.Index"
 ---
@@ -55,10 +58,10 @@ Defaults son razonables: en local sin TLS, no necesitás bloque `configure`.
 
 | Modelo | Class methods | Instance methods | Notas |
 |---|---|---|---|
-| `Service` | `all(filters)`, `find(id)`, `where(filters)`, `create(attrs)` | `update(attrs)`, `restart`, `destroy`, `logs(query)`, `reload`, `persisted?`, `id` | CRUD completo + force-recreate de tasks; `create`/`update` aceptan `registry_auth:` (+ `update`: `registry_auth_from:`) para auth de registry privado |
+| `Service` | `all(filters)`, `find(id)`, `where(filters)`, `create(attrs)` | `update(attrs)`, `restart`, `destroy`, `logs(query)`, `reload`, `persisted?`, `id` | CRUD completo + force-recreate de tasks; `create`/`update` aceptan `registry_auth:` (+ `update`: `registry_auth_from:`) para auth de registry privado; `where(status: true)` puebla `ServiceStatus` (único deseado legible de un service `global`) |
 | `Node` | `all(filters)`, `find(id)`, `where(filters)` | `update(attrs)`, `destroy` | No `create` (los nodos se unen fuera de la gema) |
 | `Task` | `all(filters)`, `find(id)`, `where(filters)` | `logs(query)`, `reload` | Read-only (generados por orquestador) |
-| `Container` | `all(filters)`, `find(id)`, `where(filters)` | `start`, `stop`, `destroy`, `logs(query)` | **No `create`** (gap conocido, fuera F1) |
+| `Container` | `all(filters)`, `find(id)`, `where(filters)`, `create(attrs)` | `start`, `stop`, `destroy`, `logs(query)` | `create` manda `name` por query string (`create_query_params`) — en el body Docker lo descarta en silencio |
 | `Image` | `all(filters)`, `find(id)`, `pull(image_reference, registry_auth:)` | `destroy` | **No `create`** (retirado; `Image` ya no es Creatable). `pull` = pull explícito síncrono → `{status, image_ref, digest?}`; **soporta `X-Registry-Auth`** para registries privados |
 | `Network` | `all(filters)`, `find(id)`, `create(attrs)` | `update(attrs)`, `destroy` | CRUD completo |
 | `Volume` | `all(filters)`, `find(id)`, `create(attrs)` | `destroy` | No `update` (Docker no lo soporta). Respuesta wrapped vía `root_key = "Volumes"` |
@@ -77,6 +80,11 @@ DockerSwarm::Service.all(label: ["env=production"])
 DockerSwarm::Node.all(role: ["manager"])
 DockerSwarm::Container.all(status: ["running"])
 
+# Listar pidiendo ServiceStatus (query param propio, NO filtro; Engine API >= v1.41)
+DockerSwarm::Service.where(status: true).each do |svc|
+  svc.ServiceStatus # => { "RunningTasks" => 2, "DesiredTasks" => 3, "CompletedTasks" => 0 } | nil
+end
+
 # Lookup graceful (nil si 404)
 service = DockerSwarm::Service.find("svc-id")  # => Service | nil
 
@@ -95,7 +103,7 @@ service.restart
 # Destroy graceful (nil si 404)
 service.destroy
 
-# Logs raw
+# Logs (ya demultiplexados: sin cabeceras de frame)
 service.logs(stdout: 1, stderr: 1)
 
 # Health check
@@ -130,7 +138,10 @@ Todas heredan de `DockerSwarm::Error`. Tres formas de acceso equivalentes: `Dock
 - **Retries automáticos sólo en métodos seguros** (GET/HEAD/PUT/DELETE/OPTIONS). POST/PATCH **no** reintentan para evitar duplicados — si el socket se cae durante un `create`, el caller decide qué hacer. Ver §3.5 de `docs/behavior/behavior.md`.
 - **`Spec` se mergea con `deep_merge` en updates**, no se reemplaza. Pasale sólo los campos que cambian: `service.update(Mode: {...})`, no `service.update(Spec: {...completo})`.
 - **`assign_attributes` muta antes de validar.** Si `update` falla por `valid?` o por el API, la instancia local quedó mutada. Hacé `reload` si necesitás estado limpio.
-- **`Container.create` no existe** en la gema (gap intencional F1). Si necesitás crear containers standalone, usá `DockerSwarm.request(method: :post, path: "containers/create", ...)` directo.
+- **`Container.create` manda el nombre por query string.** Docker **descarta en silencio** un `name:` en el body y responde `201`: el container nace con nombre aleatorio y un reintento duplica en vez de adoptar. La gema lo resuelve sola vía `Container.create_query_params == %w[name]` — pero si armás el request por afuera (`DockerSwarm.request`), el `?name=` es tuyo. Ver ADR-025 cláusula 1 y §3.11 de `docs/behavior/behavior.md`.
+- **`where` parte las claves en dos: query params propios vs. `?filters=`.** Solo lo declarado en `Base.index_query_params` (`%i[all force limit since before]`, más `:status` en `Service`) viaja en la URL; **todo lo demás se serializa como filtro de Docker**. Si le pasás un query param propio que el modelo no declara, no llega: va dentro de `filters` y el Engine lo rechaza o lo ignora — sin error que indique que iba en la URL. Los nombres no son globales: `status` es query param en `/services` y **filtro válido** en `/containers/json`.
+- **`ServiceStatus` solo aparece con `Service.where(status: true)`**, y es el **único** lugar donde el Engine publica el deseado de un service en modo `global` (un replicado lo tiene en `Spec.Mode.Replicated.Replicas`; un global no tiene ese campo). Sin `DesiredTasks` un global corriendo en 2 de 3 nodos elegibles es indistinguible de uno sano. Requiere API ≥ v1.41 y **degrada en silencio**: la gema no fija `?version=`, así que en un Engine anterior el parámetro se ignora y `ServiceStatus` llega `nil` — no hay señal de "no soportado", el consumidor tiene que tolerarlo. Y **`DesiredTasks: 0` no es "sin nodos elegibles"**: en un `global` recién creado el Engine publica los tres contadores en 0 y calcula el deseado después (~1s, medido), así que hay una ventana donde `RunningTasks == DesiredTasks == 0` y comparar los dos números miente — tratá `DesiredTasks.positive?` como precondición para decidir salud. Ver §3.12 de `docs/behavior/behavior.md`.
+- **`logs` devuelve texto ya demultiplexado.** Sin TTY el Engine enmarca cada fragmento con 8 bytes de cabecera; `Middleware::LogStreamDemuxer` los saca en `Container`, `Service` y `Task`. Dos consecuencias: **`stdout` y `stderr` vienen intercalados** en un solo String (si necesitás un dato puntual, delimitalo en origen desde el `Cmd`), y **un frame partido entre chunks no se reensambla** — el demux es todo-o-nada, así que ante cualquier inconsistencia te devuelve el body intacto en vez de texto a medias. Con `follow: 1` el body no llega completo, así que no esperes demux ahí.
 - **`Image.create` retirado (breaking).** Ya no existe (`Image` dejó de ser Creatable; el `create` estaba roto y sin consumidores). Usá `Image.pull(image_reference, registry_auth:)`.
 - **Auth de registry privado soportado** vía credencial opaca base64url en `registry_auth:` — `Image.pull(ref, registry_auth:)`, `Service.create(..., registry_auth:)` y `Service#update(..., registry_auth:` / `registry_auth_from:)`. Viaja por header `X-Registry-Auth` (o query `registryAuthFrom`: `spec`\|`previous-spec`, excluyentes); la gema no la mintea ni decodifica. Ver flujos 3.9/3.10 de `docs/behavior/behavior.md`.
 - **`destroy` es graceful con 404** (retorna `nil`), no con 409. Si el recurso está en uso, `Conflict` se propaga.
@@ -173,8 +184,10 @@ Logs salen en formato KV (`component=docker_swarm.connection event=request_succe
 - [`docs/config/configuracion.md`](docs/config/configuracion.md) — inventario de configuración runtime (7 opciones del bloque `configure`, sin env vars, ninguna secreta). El bloque de arriba es el resumen; shape/defaults/consumidores en el detalle.
 - [`docs/topology/topology.md`](docs/topology/topology.md) — dependencias runtime (3) + grafo de contexto.
 - [`docs/test/testing.md`](docs/test/testing.md) — estructura de la suite RSpec (unit + integration) y comandos de corrida.
+- [`docs/release/release.md`](docs/release/release.md) — canal de publicación (tag `v*` → RubyGems) + deploy/rollback/ambientes.
 - `docs/data/` — `n/a` (gema sin DB).
 - `docs/api/` (operaciones), `docs/events/` — `n/a` (la gema no expone superficie HTTP/CLI/eventos propia; su superficie pública es la interfaz Ruby).
+- `docs/security/`, `docs/multi-tenancy/`, `docs/data-lifecycle/` — `n/a` (sin authn/authz propios —la frontera auth-hacia-Docker está en `docs/consumed` §a—; gema stateless sin scope de tenant; sin persistencia/PII/retención).
 
 ## Versionado del contrato
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docker-swarm
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Gabriel
@@ -113,6 +113,7 @@ files:
 - lib/docker_swarm/errors.rb
 - lib/docker_swarm/log_helper.rb
 - lib/docker_swarm/middleware/error_handler.rb
+- lib/docker_swarm/middleware/log_stream_demuxer.rb
 - lib/docker_swarm/middleware/request_encoder.rb
 - lib/docker_swarm/middleware/response_json_parser.rb
 - lib/docker_swarm/models/config.rb
@@ -129,15 +130,15 @@ files:
 - lib/docker_swarm/registry_auth.rb
 - lib/docker_swarm/version.rb
 - skill/SKILL.md
-homepage: https://github.com/gedera/docker-swarm
+homepage: https://github.com/sequre/docker-swarm
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/gedera/docker-swarm
-  source_code_uri: https://github.com/gedera/docker-swarm
-  changelog_uri: https://github.com/gedera/docker-swarm/blob/v0.8.0/CHANGELOG.md
-  bug_tracker_uri: https://github.com/gedera/docker-swarm/issues
-  documentation_uri: https://github.com/gedera/docker-swarm/blob/v0.8.0/skill/SKILL.md
+  homepage_uri: https://github.com/sequre/docker-swarm
+  source_code_uri: https://github.com/sequre/docker-swarm
+  changelog_uri: https://github.com/sequre/docker-swarm/blob/v0.10.0/CHANGELOG.md
+  bug_tracker_uri: https://github.com/sequre/docker-swarm/issues
+  documentation_uri: https://github.com/sequre/docker-swarm/blob/v0.10.0/skill/SKILL.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: