test: volumes long-form conformance + integration; promote docs

Author: lesnik512

architecture/supported-subset.md

@@ -755,7 +755,26 @@ boolean-typed exception in this group, validated as an actual bool like
 
 ## Volumes
 
-Short syntax only; the long mapping form raises. The `volumes` key itself
+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
+(`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.
+
+The `volumes` key itself
 must be a list — a bare string raises, rather than being destructured one
 character at a time. A `source:target` entry is one of two kinds, told apart
 by whether `source` matches Docker's own volume-name grammar

planning/deferred.md

@@ -11,8 +11,14 @@ subset, not a bug and not a design position. Each item below is a **form** of a
 capability compose2pod already supports, refused only because the parser was
 never written. Every one was measured against `docker compose config` v5.1.2.
 
-- **Long-form `volumes`.** The mapping form raises; podman expresses it with
-  `--mount`.
+- **Long-form `volumes` nested option maps.** The mapping form itself
+  (`type`/`source`/`target`/`read_only`/`consistency`) is now accepted and
+  emitted as `--mount` (`2026-07-16.05-volumes-long-form`). Still refused:
+  the nested `bind:`/`volume:`/`tmpfs:` option map a long-form entry may
+  carry (`propagation`, `subpath`, `tmpfs.size`/`tmpfs.mode`) — podman's
+  `--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.
 - **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
@@ -29,9 +35,10 @@ never written. Every one was measured against `docker compose config` v5.1.2.
   tilde-bind-mount fix that discovered it.
 
 **Revisit trigger:** a user reports a compose file that `docker compose` runs and
-compose2pod refuses — most likely long-form `volumes`, a common form in
-hand-written and generated compose files alike. The conformance harness reports
-these as `over-reject`, so they stay visible rather than forgotten.
+compose2pod refuses — most likely a long-form `volumes` entry's nested
+`bind:`/`volume:`/`tmpfs:` option map, now that the mapping form itself is
+accepted, or the Windows drive-letter bind above. The conformance harness
+reports these as `over-reject`, so they stay visible rather than forgotten.
 
 Two other `over-reject` cells the harness reports — `sysctls: ["a"]` and
 `volumes: ["a"]` — are *not* deferred parsers: they are measured legitimate

tests/conformance/test_corpus.py

@@ -82,3 +82,18 @@ def test_healthcheck_compound_duration_is_no_longer_an_over_rejection(
     """
     path = Path(__file__).parent / "corpus" / "healthcheck_compound_duration.yaml"
     assert assert_rule(yaml.safe_load(path.read_text())) == "both-accept"
+
+
+def test_volumes_long_form_is_no_longer_an_over_rejection(
+    assert_rule: Callable[[dict[str, Any]], str],
+) -> None:
+    """The long-syntax (mapping) volume entry now parses instead of raising.
+
+    Same reasoning as the over-rejection tests above: the generic corpus run alone
+    would stay green even pre-fix, filing `volumes_long_form` under the allowed
+    'over-reject' verdict instead of catching a regression. The stronger claim --
+    both oracles ACCEPT `{type: bind, source: ./data, target: /data}` -- needs
+    this dedicated assertion on the verdict itself.
+    """
+    path = Path(__file__).parent / "corpus" / "volumes_long_form.yaml"
+    assert assert_rule(yaml.safe_load(path.read_text())) == "both-accept"

tests/integration/test_volume_long_form.py

@@ -0,0 +1,22 @@
+"""Long-form volumes: a {type: bind} mapping round-trips a host file into the container."""
+
+from collections.abc import Callable
+from pathlib import Path
+
+from tests.integration.conftest import PodRun
+
+
+def test_long_form_bind_mount_is_read(run_pod: Callable[..., PodRun], tmp_path: Path) -> None:
+    (tmp_path / "data.txt").write_text("mount-ok-73\n")
+    compose = {
+        "services": {
+            "app": {
+                "image": "busybox:1.36",
+                "volumes": [{"type": "bind", "source": "./data.txt", "target": "/data.txt", "read_only": True}],
+                "command": ["cat", "/data.txt"],
+            },
+        },
+    }
+    run = run_pod(compose, target="app", project_dir=tmp_path)
+    assert run.returncode == 0, run.stderr
+    assert "mount-ok-73" in run.stdout