fix: refuse a relative long-form volume target

podman rejects a relative --mount target for every type ("must be an
absolute path"); docker accepts one, so scope A's long-form volumes
silently emitted a script that fails on podman -- a rule-two gap,
inconsistent with the short-form anonymous-volume refusal. A ${VAR}
target is carved out (host-dependent), matching every other
values.has_variable case in parsing.py.

Also corrects two doc-accuracy issues found in final review:
'image' is a deferred parser gap (docker accepts, podman can express
it), not a permanent rule-two refusal like cluster/npipe; and
tmpfs-with-source is a podman rule-two refusal, not a docker-schema
rule (docker accepts it).

Author: lesnik512

architecture/supported-subset.md

@@ -757,22 +757,36 @@ boolean-typed exception in this group, validated as an actual bool like
 
 A `volumes` entry may be the short string syntax or the long-form mapping
 `{type, source, target, read_only, consistency}`. `type` must be `bind`,
-`volume`, or `tmpfs`; `cluster`, `npipe`, and `image` are refused (the latter
-is podman-inexpressible, and `cluster`/`npipe` fall out as an unrecognized
-`type` alongside them). Each is emitted as a single `--mount` flag
+`volume`, or `tmpfs`. `cluster` and `npipe` are refused as permanent rule-two
+limitations — podman's `--mount` rejects them (`invalid filesystem type`) and
+can never express them. `image` is refused too, but for a different reason:
+docker accepts it and podman *can* express it (`--mount type=image,...`
+succeeds) — scope A's parser simply does not parse it yet, so it is a
+deferred parser gap (`planning/deferred.md`), not a rule-two refusal. The
+nested `bind:`/`volume:`/`tmpfs:` option maps (`propagation`, `subpath`,
+`tmpfs.size`/`tmpfs.mode`, etc.) fall out as unsupported keys and raise for
+the same deferred-parser reason; `nocopy` is podman-inexpressible regardless.
+A `target` must be an absolute path (a `${VAR}` reference is accepted, being
+host-dependent) — podman's `--mount` rejects a relative target for every
+type (`invalid container path "rel", must be an absolute path`) even though
+docker accepts one, matching the short-form anonymous-volume refusal (below).
+A `tmpfs`-type entry's `source` is refused even though docker accepts one:
+podman's `--mount` has no way to express a `source` on a `tmpfs` mount
+(`"source" option not supported for "tmpfs" mount types`), so this is a
+rule-two refusal, not a docker-schema rule.
+
+Each accepted entry is emitted as a single `--mount` flag
 (`compose2pod/emit.py`'s `_mount_flag`) rather than `-v`: `type=<type>`,
 `source=<source>` (a relative bind `source` is resolved against
 `--project-dir`, the same as the short form), `target=<target>`, and a
 trailing `ro` when `read_only` is truthy — `read_only` accepts the quoted
 `"true"`/`"false"` form via the same `is_bool_like` check every other
 boolean field uses. `consistency` is accepted and validated as a string but
-otherwise ignored — podman's `--mount` has no consistency knob. The nested
-`bind:`/`volume:`/`tmpfs:` option maps (`propagation`, `subpath`,
-`tmpfs.size`/`tmpfs.mode`, etc.) fall out as unsupported keys and raise;
-`nocopy` is podman-inexpressible regardless. A long-form `volume`-type entry
-whose `source` is a bare identifier is cross-checked against the top-level
-`volumes:` block exactly like a short-form named volume (below) — a
-`bind`/`tmpfs` entry's `source`, or an absent one, needs no declaration.
+otherwise ignored — podman's `--mount` has no consistency knob. A long-form
+`volume`-type entry whose `source` is a bare identifier is cross-checked
+against the top-level `volumes:` block exactly like a short-form named
+volume (below) — a `bind`/`tmpfs` entry's `source`, or an absent one, needs
+no declaration.
 
 The `volumes` key itself
 must be a list — a bare string raises, rather than being destructured one

compose2pod/parsing.py

@@ -207,9 +207,17 @@ def _validate_volume_long_form(name: str, entry: dict[str, Any]) -> None:
     if vtype not in _VOLUME_LONG_TYPES:
         msg = f"service {name!r}: volume 'type' must be one of {list(_VOLUME_LONG_TYPES)}"
         raise UnsupportedComposeError(msg)
-    if not isinstance(entry.get("target"), str):
+    target = entry.get("target")
+    if not isinstance(target, str):
         msg = f"service {name!r}: volume 'target' must be a string"
         raise UnsupportedComposeError(msg)
+    if not target.startswith("/") and not values.has_variable(target):
+        # podman rejects a relative --mount target for every type ("must be
+        # an absolute path"); docker accepts it. A ${VAR} target is
+        # host-dependent, so it is carved out like every other
+        # values.has_variable case in this file.
+        msg = f"service {name!r}: volume 'target' must be an absolute path"
+        raise UnsupportedComposeError(msg)
     _validate_volume_long_form_source(name, vtype, entry.get("source"))
     if "read_only" in entry and not values.is_bool_like(entry["read_only"]):
         msg = f"service {name!r}: volume 'read_only' must be a boolean"

planning/changes/2026-07-16.05-volumes-long-form.md

@@ -1,5 +1,5 @@
 ---
-summary: Accept the long-form (mapping) `volumes` entry — `{type, source, target, read_only, consistency}` for `type` in bind/volume/tmpfs — matching `docker compose config` v5.1.2, emitting `podman run --mount`; nested option maps and the cluster/npipe/image types stay refused (the former a tracked scope follow-up, the latter rule-two refusals podman cannot express).
+summary: Accept the long-form (mapping) `volumes` entry — `{type, source, target, read_only, consistency}` for `type` in bind/volume/tmpfs — matching `docker compose config` v5.1.2, emitting `podman run --mount`; nested option maps and the `image` type stay refused as a tracked deferred-parser gap (podman could express `image`; scope A doesn't parse it yet); `cluster`/`npipe` stay refused as permanent rule-two limitations podman cannot express.
 ---
 
 # Design: long-form (mapping) volumes
@@ -10,9 +10,11 @@ summary: Accept the long-form (mapping) `volumes` entry — `{type, source, targ
 "only short volume syntax is supported". This change accepts the long form
 `{type, source, target, read_only, consistency}` for `type` in
 `bind`/`volume`/`tmpfs`, emitting `podman run --mount type=…,target=…[,source=…][,ro]`.
-The nested `bind:`/`volume:`/`tmpfs:` option maps are left as a tracked
-follow-up (scope A); `cluster`/`npipe`/`image` types are refused as rule-two
-limitations (podman: `invalid filesystem type`).
+The nested `bind:`/`volume:`/`tmpfs:` option maps and the `image` type are
+left as a tracked follow-up (scope A doesn't parse them yet, but podman
+could express both — a deferred parser gap, not a refusal);
+`cluster`/`npipe` are refused as permanent rule-two limitations (podman:
+`invalid filesystem type`).
 
 ## Motivation
 
@@ -28,12 +30,18 @@ config` v5.1.2 and podman 6.0.1.
 A `volumes` list entry may be a string (short, unchanged) or a mapping (long
 form). The mapping is a strict schema:
 
-- `type` — **required**; `bind`/`volume`/`tmpfs` supported. `cluster`/`npipe`/`image`
-  refused (podman `--mount` rejects them: `invalid filesystem type`).
+- `type` — **required**; `bind`/`volume`/`tmpfs` supported. `cluster`/`npipe`
+  refused: rule-two limitations podman `--mount` rejects (`invalid filesystem
+  type`) and can never express. `image` also refused in scope A, but for a
+  different reason — docker accepts it and podman `--mount type=image,...`
+  *can* express it, so it is a deferred parser gap (`planning/deferred.md`),
+  not a rule-two refusal.
 - `target` — **required** string.
 - `source` — **required** string for `bind` (Docker: "field Source must not be
-  empty"); optional string for `volume` (absent → anonymous); not allowed for
-  `tmpfs`.
+  empty"); optional string for `volume` (absent → anonymous); docker accepts
+  a `source` on `tmpfs` too, but podman's `--mount` cannot express one
+  (`"source" option not supported for "tmpfs" mount types`) — a rule-two
+  refusal, not a docker-schema rule, so compose2pod refuses it here.
 - `read_only` — optional bool via `values.is_bool_like` (the quoted form works,
   reusing `2026-07-16.01`).
 - `consistency` — optional, accepted and ignored (legacy macOS hint; no podman
@@ -75,10 +83,12 @@ The `--mount` value is a single comma-joined `Expand` token, so a `${VAR}` in
 ## Non-goals
 
 - **Nested `bind`/`volume`/`tmpfs` option maps** (`propagation`, `subpath`,
-  `tmpfs.size/mode`, `nocopy`) — scope A leaves these refused; tracked as the one
-  remaining long-form piece. `volume.nocopy` would be a rule-two refusal anyway
-  (podman: `invalid mount option`); the rest podman can express.
-- **`cluster`/`npipe`/`image` types** — rule-two refusals (podman: `invalid
+  `tmpfs.size/mode`, `nocopy`) and the **`image` type** — scope A leaves these
+  refused; tracked as deferred parser gaps (`planning/deferred.md`), not
+  rule-two refusals — podman can express all of them (`--mount
+  type=image,...` succeeds) except `volume.nocopy`, which would be a genuine
+  rule-two refusal anyway (podman: `invalid mount option`).
+- **`cluster`/`npipe` types** — permanent rule-two refusals (podman: `invalid
   filesystem type`).
 - **`-v`-vs-`--mount` for the short form** — the short string form keeps `-v`.
 

planning/deferred.md

@@ -19,6 +19,12 @@ never written. Every one was measured against `docker compose config` v5.1.2.
   `--mount` can express these, so they are a genuine parser gap, not a
   design position; `nocopy` is podman-inexpressible and would stay refused
   either way.
+- **Long-form `volumes` `image` mount type.** `type: image` (docker: ACCEPTS,
+  measured `docker compose config` v5.1.2) is refused by scope A's parser
+  (`type` must be `bind`/`volume`/`tmpfs`), but podman *can* express it
+  (`--mount type=image,source=busybox:1.36,target=/img` succeeds, measured
+  podman 6.0.1) — a genuine parser gap, not a rule-two refusal like
+  `cluster`/`npipe` (podman: `invalid filesystem type`).
 - **Windows drive-letter volume source.** `volumes: ["C:\data:/var"]` with no
   top-level declaration: Docker ACCEPTS (measured, `docker compose config`
   v5.1.2 -- it special-cases a leading `<letter>:\` so the drive letter stays

tests/test_parsing.py

@@ -137,6 +137,24 @@ def test_long_volume_entry_rejects(self) -> None:
             with pytest.raises(UnsupportedComposeError, match=msg):
                 validate({"services": {"app": {"image": "x", "volumes": vols}}})
 
+    def test_long_volume_relative_target_rejected(self) -> None:
+        # podman rejects a relative --mount target for every type ("must be an
+        # absolute path"); docker accepts it. Matches the short-form
+        # anonymous-volume refusal above.
+        for entry in (
+            {"type": "volume", "target": "rel"},
+            {"type": "bind", "source": "/a", "target": "rel"},
+        ):
+            with pytest.raises(UnsupportedComposeError, match=r"volume 'target' must be an absolute path"):
+                validate({"services": {"app": {"image": "x", "volumes": [entry]}}})
+
+    def test_long_volume_variable_target_accepted(self) -> None:
+        # A ${VAR}-carrying target is host-dependent -- accepted, matching
+        # every other values.has_variable carve-out in parsing.py.
+        assert (
+            validate({"services": {"app": {"image": "x", "volumes": [{"type": "volume", "target": "${MNT}"}]}}}) == []
+        )
+
     def test_anonymous_volume_is_accepted(self) -> None:
         assert validate({"services": {"app": {"image": "x", "volumes": ["/var/cache/models"]}}}) == []