feat: accept long-form volume nested option maps (#73)

Accepts the long-form volume nested option maps (bind/volume/tmpfs) for the podman-expressible
options: bind {propagation, selinux->relabel}, volume {subpath}, tmpfs {size, mode}, emitted as
--mount options. propagation narrowed to podman's enum; tmpfs.size/mode non-negative (mode a
non-negative integer -- a float fails podman's crun). Refused (rule-two): bind.create_host_path,
volume.nocopy. A sub-map not matching type is refused (stricter than docker).

Design: planning/changes/2026-07-17.02-volumes-nested-options.md

Author: lesnik512

architecture/supported-subset.md

@@ -762,10 +762,22 @@ 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.
+deferred parser gap (`planning/deferred.md`), not a rule-two refusal. A
+long-form entry may also carry the nested option sub-map matching its own
+`type` — `bind: {propagation, selinux}`, `volume: {subpath}`, `tmpfs: {size,
+mode}` — each accepted and appended to the emitted `--mount` value:
+`propagation` (narrowed to podman's enum `private`/`rprivate`/`shared`/
+`rshared`/`slave`/`rslave`) becomes `bind-propagation=<value>`; `selinux`
+(`z`/`Z`) becomes `relabel=shared`/`relabel=private`; `subpath` becomes
+`subpath=<value>`; `tmpfs.size`/`tmpfs.mode` become `tmpfs-size=<value>`/
+`tmpfs-mode=<value>`. Two options stay refused as permanent rule-two
+limitations because podman's `--mount` cannot express them at all:
+`bind.create_host_path` and `volume.nocopy`. A sub-map that does not match
+the entry's own `type` (a `bind:` map on a `type: volume` entry, for
+example) is refused too — docker accepts and silently ignores a mismatched
+sub-map, but compose2pod treats it as a likely mistake and refuses it, a
+deliberate stricter-than-docker check.
+
 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

compose2pod/emit.py

@@ -94,6 +94,22 @@ def _env_file_flags(svc: dict[str, Any], project_dir: str) -> list[Token]:
     return flags
 
 
+def _nested_mount_parts(vtype: str, options: dict[str, Any]) -> list[str]:
+    """Map a long-form volume entry's validated `bind`/`volume`/`tmpfs` sub-map to `--mount` options."""
+    if vtype == "bind":
+        parts = [f"bind-propagation={options['propagation']}"] if "propagation" in options else []
+        if "selinux" in options:
+            parts.append(f"relabel={'shared' if options['selinux'] == 'z' else 'private'}")
+        return parts
+    if vtype == "volume":
+        return [f"subpath={options['subpath']}"] if "subpath" in options else []
+    # vtype == "tmpfs": the gate validates `type` to one of bind/volume/tmpfs, so no other branch is reachable.
+    parts = [f"tmpfs-size={options['size']}"] if "size" in options else []
+    if "mode" in options:
+        parts.append(f"tmpfs-mode={options['mode']}")
+    return parts
+
+
 def _mount_flag(entry: dict[str, Any], project_dir: str) -> list[Token]:
     """Render one long-form volume mapping as a `--mount` value."""
     parts = [f"type={entry['type']}"]
@@ -105,6 +121,8 @@ def _mount_flag(entry: dict[str, Any], project_dir: str) -> list[Token]:
     parts.append(f"target={entry['target']}")
     if as_bool(entry.get("read_only", False)):
         parts.append("ro")
+    vtype = entry["type"]
+    parts += _nested_mount_parts(vtype, entry.get(vtype, {}))
     return ["--mount", Expand(value=",".join(parts))]
 
 

compose2pod/parsing.py

@@ -162,6 +162,18 @@ def _classify_volume(volume: str) -> tuple[str, str | None]:
 
 _VOLUME_LONG_TYPES = ("bind", "volume", "tmpfs")
 _VOLUME_LONG_KEYS = {"type", "source", "target", "read_only", "consistency"}
+# Docker's own per-type nested option map keys (measured, docker compose config
+# v5.1.2). `create_host_path`/`nocopy` are real docker keys, so they land here
+# (not treated as unknown) -- rule-two refuses them separately, in
+# `_validate_volume_options`, with a "not supported" message rather than an
+# "unknown key" one.
+_VOLUME_OPTION_KEYS = {
+    "bind": {"propagation", "selinux", "create_host_path"},
+    "volume": {"subpath", "nocopy"},
+    "tmpfs": {"size", "mode"},
+}
+_PROPAGATION_VALUES = {"private", "rprivate", "shared", "rshared", "slave", "rslave"}
+_SELINUX_VALUES = {"z", "Z"}
 
 
 def _validate_service_volumes(name: str, svc: dict[str, Any]) -> None:
@@ -193,20 +205,24 @@ def _validate_service_volumes(name: str, svc: dict[str, Any]) -> None:
 def _validate_volume_long_form(name: str, entry: dict[str, Any]) -> None:
     """Check one long-syntax volume mapping against Docker's strict schema (measured, v5.1.2).
 
-    Scope A: type (bind/volume/tmpfs), source, target, read_only, consistency.
-    The nested bind/volume/tmpfs option maps fall out as unknown keys (refused,
-    tracked in planning/deferred.md); cluster/npipe/image types are refused
-    (podman cannot express them).
+    type (bind/volume/tmpfs), source, target, read_only, consistency, plus the
+    one nested option map matching `type` (a mismatched sub-map is refused --
+    a deliberate stricter-than-docker check; docker accepts-and-ignores it).
+    cluster/npipe/image types are refused (podman cannot express them).
+
+    `type` is validated before the unknown-key check (unlike every other field
+    here) because the check itself needs `vtype` to know which sub-map key --
+    `bind`/`volume`/`tmpfs` -- the entry is allowed to carry alongside it.
     """
     require_string_keys(f"service {name!r}: volume", entry)
-    unknown = set(entry) - _VOLUME_LONG_KEYS
-    if unknown:
-        msg = f"service {name!r}: volume: unsupported keys {sorted(unknown)}"
-        raise UnsupportedComposeError(msg)
     vtype = entry.get("type")
     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)
+    unknown = set(entry) - _VOLUME_LONG_KEYS - {vtype}
+    if unknown:
+        msg = f"service {name!r}: volume: unsupported keys {sorted(unknown)}"
+        raise UnsupportedComposeError(msg)
     target = entry.get("target")
     if not isinstance(target, str):
         msg = f"service {name!r}: volume 'target' must be a string"
@@ -225,6 +241,86 @@ def _validate_volume_long_form(name: str, entry: dict[str, Any]) -> None:
     if "consistency" in entry and not isinstance(entry["consistency"], str):
         msg = f"service {name!r}: volume 'consistency' must be a string"
         raise UnsupportedComposeError(msg)
+    if vtype in entry:
+        _validate_volume_options(name, vtype, entry[vtype])
+
+
+def _validate_bind_options(name: str, options: dict[str, Any]) -> None:
+    """Check a long-form volume entry's `bind:` sub-map (measured, v5.1.2).
+
+    `create_host_path` is a real Docker key, but podman's `--mount` cannot
+    express it, so it is refused with a "not supported" message rather than
+    folded into the generic unknown-key check the caller already ran.
+    """
+    if "create_host_path" in options:
+        msg = f"service {name!r}: bind 'create_host_path' is not supported (podman cannot express it)"
+        raise UnsupportedComposeError(msg)
+    if "propagation" in options and options["propagation"] not in _PROPAGATION_VALUES:
+        msg = f"service {name!r}: bind 'propagation' must be one of {sorted(_PROPAGATION_VALUES)}"
+        raise UnsupportedComposeError(msg)
+    if "selinux" in options and options["selinux"] not in _SELINUX_VALUES:
+        msg = f"service {name!r}: bind 'selinux' must be 'z' or 'Z'"
+        raise UnsupportedComposeError(msg)
+
+
+def _validate_volume_type_options(name: str, options: dict[str, Any]) -> None:
+    """Check a long-form volume entry's `volume:` sub-map (measured, v5.1.2).
+
+    `nocopy` is a real Docker key, but podman's `--mount` cannot express it,
+    so it is refused with a "not supported" message rather than folded into
+    the generic unknown-key check the caller already ran.
+    """
+    if "nocopy" in options:
+        msg = f"service {name!r}: volume 'nocopy' is not supported (podman cannot express it)"
+        raise UnsupportedComposeError(msg)
+    if "subpath" in options and not isinstance(options["subpath"], str):
+        msg = f"service {name!r}: volume 'subpath' must be a string"
+        raise UnsupportedComposeError(msg)
+
+
+def _validate_tmpfs_options(name: str, options: dict[str, Any]) -> None:
+    """Check a long-form volume entry's `tmpfs:` sub-map (measured, v5.1.2).
+
+    `size` and `mode` are both unsigned in Docker's own decoder: a negative
+    native number is refused ("size"/"cannot parse as uint32: -1 overflows"),
+    measured against `docker compose config` v5.1.2. `mode` additionally
+    tightens `validate_native_number`'s float acceptance down to integers
+    only -- Docker itself accepts a float `mode` (it round-trips it verbatim),
+    but podman 6.0.1's `crun` fails to mount it at run time ("crun: mount
+    tmpfs: Invalid argument"), so accepting one here would be a real green in
+    `docker compose config` that is a false green for the generated script.
+    """
+    if "size" in options:
+        size = options["size"]
+        values.validate_size(name, "tmpfs size", size, allow_fractional=False)
+        if isinstance(size, (int, float)) and not isinstance(size, bool) and size < 0:
+            msg = f"service {name!r}: tmpfs size must be non-negative"
+            raise UnsupportedComposeError(msg)
+    if "mode" in options:
+        mode = options["mode"]
+        if isinstance(mode, bool) or not isinstance(mode, int) or mode < 0:
+            msg = f"service {name!r}: tmpfs mode must be a non-negative integer"
+            raise UnsupportedComposeError(msg)
+
+
+_VOLUME_OPTION_VALIDATORS: dict[str, Callable[[str, dict[str, Any]], None]] = {
+    "bind": _validate_bind_options,
+    "volume": _validate_volume_type_options,
+    "tmpfs": _validate_tmpfs_options,
+}
+
+
+def _validate_volume_options(name: str, vtype: str, options: Any) -> None:  # noqa: ANN401 - Compose values are untyped YAML/JSON
+    """Check a long-form volume entry's nested option map (the one matching `type`), measured v5.1.2."""
+    if not isinstance(options, dict):
+        msg = f"service {name!r}: {vtype} options must be a mapping"
+        raise UnsupportedComposeError(msg)
+    require_string_keys(f"service {name!r}: {vtype} options", options)
+    unknown = set(options) - _VOLUME_OPTION_KEYS[vtype]
+    if unknown:
+        msg = f"service {name!r}: {vtype} options: unsupported keys {sorted(unknown)}"
+        raise UnsupportedComposeError(msg)
+    _VOLUME_OPTION_VALIDATORS[vtype](name, options)
 
 
 def _validate_volume_long_form_source(name: str, vtype: str, source: Any) -> None:  # noqa: ANN401 - Compose values are untyped YAML/JSON

planning/changes/2026-07-17.02-volumes-nested-options.md

@@ -0,0 +1,114 @@
+---
+summary: Accept the long-form volume nested option maps (`bind:`/`volume:`/`tmpfs:`) for the options podman `--mount` can express — `propagation`, `selinux` (translated z/Z → `relabel=shared`/`private`), `subpath`, `tmpfs.size`, `tmpfs.mode` — matching `docker compose config` v5.1.2; `volume.nocopy` and `bind.create_host_path` stay refused (rule-two, podman cannot express them), and a sub-map that does not match the entry's `type` is refused (a deliberate stricter-than-Docker check catching a likely mistake).
+---
+
+# Design: long-form volume nested option maps
+
+## Summary
+
+The scope-A long-form volumes work (`2026-07-16.05`) refused the nested
+`bind:`/`volume:`/`tmpfs:` option maps as unknown keys. This accepts them for the
+options podman `--mount` can express, appending the mapped options to the
+`--mount` value. Options podman cannot express (`volume.nocopy`,
+`bind.create_host_path`) stay refused (rule-two). A sub-map keyed for a `type`
+other than the entry's own is refused.
+
+## Motivation
+
+The nested option maps are the remaining long-form `volumes` gap
+(`planning/deferred.md`). Measured against `docker compose config` v5.1.2 and
+podman 6.0.1.
+
+## Design
+
+### Grammar (measured)
+
+For a long-form entry `{type, source, target, read_only, consistency}`, add one
+optional sub-map — the one matching `type`:
+
+- **`bind:`** (only for `type: bind`)
+  - `propagation` — enum `private`/`rprivate`/`shared`/`rshared`/`slave`/`rslave`
+    → `bind-propagation=<value>`. (Docker accepts any string, but podman
+    validates this enum, so compose2pod narrows to it — a rule-two narrowing:
+    a propagation podman rejects would fail at run time.)
+  - `selinux` — enum `z`/`Z` → translated to `relabel=shared` (`z`) /
+    `relabel=private` (`Z`). (podman's `--mount` spells the SELinux relabel as
+    `shared`/`private`, not `z`/`Z`.)
+  - `create_host_path` — **refused** (rule-two): podman `--mount` has no
+    equivalent and does not auto-create a missing bind source. Tracked.
+- **`volume:`** (only for `type: volume`)
+  - `subpath` — string → `subpath=<value>`.
+  - `nocopy` — **refused** (rule-two): podman `--mount` rejects it
+    (`volume-nocopy: invalid mount option`). Tracked.
+- **`tmpfs:`** (only for `type: tmpfs`)
+  - `size` — a number or size string (`1000`, `"1m"`; a fractional float is
+    refused) → `tmpfs-size=<value>`.
+  - `mode` — a native number (`1777`; a string is refused) → `tmpfs-mode=<value>`.
+- Unknown sub-map key → refused.
+- **A sub-map not matching `type`** (`bind:` on a `type: volume`, etc.) →
+  **refused**. Docker accepts a mismatched sub-map and silently ignores it; a
+  mismatched sub-map is always a mistake, so compose2pod refuses it — a
+  deliberate stricter-than-Docker check (a tracked over-reject) that also keeps
+  `nocopy`/`create_host_path` unconditional refusals rather than type-dependent.
+
+### Validation (`parsing.py`)
+
+`_validate_volume_long_form` gains the matching sub-map to its allowed keys
+(base keys + `bind`/`volume`/`tmpfs` where it equals `type`). A new
+`_validate_volume_options(name, vtype, options)` enforces the per-type sub-map
+schema above (enum for `propagation`/`selinux`, size/number for `tmpfs.size/mode`,
+string for `subpath`, and the `nocopy`/`create_host_path` refusals). Presence of
+a non-matching sub-map key is refused by the same unknown-key check that already
+guards the base keys.
+
+### Emit (`emit._mount_flag`)
+
+After the existing `type`/`source`/`target`/`ro` parts, append the matching
+sub-map's mapped options, in a stable order:
+
+- `bind`: `bind-propagation=<propagation>`, `relabel=<shared|private>` (from
+  `selinux`).
+- `volume`: `subpath=<subpath>`.
+- `tmpfs`: `tmpfs-size=<size>`, `tmpfs-mode=<mode>`.
+
+Each stays part of the single comma-joined `Expand` token, so a `${VAR}` in a
+value interpolates at run time.
+
+## Non-goals
+
+- **`volume.nocopy`, `bind.create_host_path`** — rule-two refusals (podman
+  cannot express them); tracked, not deferred parsers.
+- **Accepting a mismatched sub-map** — refused by design (see Grammar); recorded
+  as a stricter-than-Docker over-reject.
+- **`cluster`/`npipe`/`image` types** — unchanged (still refused / deferred per
+  `2026-07-16.05`).
+
+## Testing (TDD; Docker + podman oracles)
+
+- **parsing**: accept each sub-map on its matching type with valid options
+  (`propagation: rshared`, `selinux: z`, `subpath: s`, `size: "1m"`/`1000`,
+  `mode: 1777`); reject a bad `propagation` enum value, a bad `selinux` value, a
+  `tmpfs.size` fractional float, a `tmpfs.mode` string, `volume.nocopy`,
+  `bind.create_host_path`, an unknown sub-map key, and a mismatched sub-map
+  (`bind:` on `type: volume`).
+- **emit**: each mapped option appears in the `--mount` value with the right
+  podman spelling; `selinux: z`→`relabel=shared`, `Z`→`relabel=private`; a
+  `${VAR}` in an option value interpolates.
+- **conformance**: a corpus doc with a `bind: {propagation}` entry flips
+  over-reject → both-accept (dedicated assertion); an integration test on real
+  podman (a bind mount with `propagation` round-trips).
+- **promotion**: `architecture/supported-subset.md` (nested options) and
+  `planning/deferred.md` (the long-form volumes bullet narrows to the refused
+  `nocopy`/`create_host_path` + mismatched-sub-map residual).
+- `just test-ci` @ 100% coverage, `just lint-ci`, `just check-planning`,
+  `just test-conformance`.
+
+## Risk
+
+- **A mapped podman option spelled wrong** (low × high): fails on podman.
+  Mitigated by the integration test (real podman round-trip) and per-option emit
+  unit tests; every spelling was measured against podman 6.0.1.
+- **`selinux` z/Z translation inverted** (low × med): measured — `z` = shared
+  (`relabel=shared`), `Z` = private (`relabel=private`); the emit test pins both.
+- **`propagation` enum drift from podman** (low × low): the six values are
+  measured accepted by both oracles; a value outside them is refused before emit.

planning/deferred.md

@@ -11,14 +11,6 @@ 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` 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.
 - **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
@@ -41,10 +33,9 @@ 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 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.
+compose2pod refuses — most likely a long-form `volumes` entry's `type: image`,
+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/corpus/volumes_long_form_bind_options.yaml

@@ -0,0 +1,9 @@
+services:
+  app:
+    image: nginx
+    volumes:
+      - type: bind
+        source: ./data
+        target: /data
+        bind:
+          propagation: rshared

tests/conformance/test_corpus.py

@@ -97,3 +97,19 @@ def test_volumes_long_form_is_no_longer_an_over_rejection(
     """
     path = Path(__file__).parent / "corpus" / "volumes_long_form.yaml"
     assert assert_rule(yaml.safe_load(path.read_text())) == "both-accept"
+
+
+def test_volumes_long_form_bind_options_is_no_longer_an_over_rejection(
+    assert_rule: Callable[[dict[str, Any]], str],
+) -> None:
+    """The long-form entry's nested `bind:` option map 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_bind_options` under
+    the allowed 'over-reject' verdict instead of catching a regression. The
+    stronger claim -- both oracles ACCEPT a `bind: {propagation: rshared}` sub-map
+    on a `type: bind` entry -- needs this dedicated assertion on the verdict
+    itself.
+    """
+    path = Path(__file__).parent / "corpus" / "volumes_long_form_bind_options.yaml"
+    assert assert_rule(yaml.safe_load(path.read_text())) == "both-accept"