docker-swarm 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61bc38a1b8f94704857812a859abbe425f57a63130655bcbaf7938f5621ad09a
-  data.tar.gz: 1b824044722bc3a3c840889b5fef843aa6eafd25576ea25811ac8ee8e688d4e3
+  metadata.gz: 8e27b0beec0476baca5222a41e38aa7b11998641c39cc15eeb16390343e8364b
+  data.tar.gz: 61faa29cc088ea4286fb864b0b2237bfd104059236e4b748168344148931ab9e
 SHA512:
-  metadata.gz: bfbb5850f24f31b4e00e7da3a90e3ed73996304c757688736cc0dcbe52bba19738e0c4a9615a79f88912f984992d603546a4a46e40f4102f356b7e718b37e983
-  data.tar.gz: c3d7d6bf0e27dd190bd4dfe78a4b09436f3dada89edbf8628552a7a17d0a63a66ffb49c6c62b2e923c5f58d6cd12a584ba819e12329e13ae90ad50079e8bdc1a
+  metadata.gz: 01b0508429e58f4878e8aa5bba874e67d57e87bf691c31ebc144da22cbeb86d89dc438f268ab85374009949e28296546747be6e0b03b718ddaa4a2df6f1e521b
+  data.tar.gz: bc02c9d23be1bacc5a8f7bee2e105cf0fdc90a75fa96d4257c41467bff9b7369a031c6c21644ac3cfc84159910bd10657371b2b9407d4c9bb270cf081d52af23

data/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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 (11 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.9.0` · cobertura: 11 flujos load-bearing (8 backfill inicial + 3 nuevos: auth de registry privado, `Image.pull` síncrono, `Container.create`)
 
 ## 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 (11)
 
 1. `Service.create` + reload
 2. `Service.update` con `Version.Index`
@@ -20,12 +20,12 @@ 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`)
 
 ### 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 +212,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 +299,40 @@ 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.
+
 ## 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 = 11. 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.9.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 |
+| 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=` / array \| Hash |
 | 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,16 @@ 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`.
 
+**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.9.0` · cobertura: API Ruby pública de la gema (`lib/docker_swarm/**`); símbolos internos marcados en §4
 
 ## 1. Resumen
 
@@ -63,11 +63,13 @@ 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`)
@@ -77,7 +79,7 @@ Inventario completo de opciones: [`docs/config/configuracion.md`](../config/conf
 | `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 | 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 +101,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.9.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.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` |

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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DockerSwarm
-  VERSION = "0.8.0"
+  VERSION = "0.9.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"
 ---
@@ -58,7 +61,7 @@ Defaults son razonables: en local sin TLS, no necesitás bloque `configure`.
 | `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 |
 | `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"` |
@@ -95,7 +98,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 +133,8 @@ 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`.
+- **`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 +177,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.9.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.9.0/CHANGELOG.md
+  bug_tracker_uri: https://github.com/sequre/docker-swarm/issues
+  documentation_uri: https://github.com/sequre/docker-swarm/blob/v0.9.0/skill/SKILL.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: