refactor: move environment into the service-key registry (#64)

Move `environment` into the SERVICE_KEYS registry as `_map("-e")`, deleting its hand-rolled validate/emit/merge. Behavior-preserving. See planning/changes/2026-07-15.17-environment-into-registry.md.

Author: lesnik512

architecture/supported-subset.md

@@ -269,6 +269,7 @@ boolean mapping value (`labels: {enabled: true}`) is normalized like
 | `devices` | `--device` (repeated) | list of strings |
 | `labels` | `--label` (repeated; null value → bare `KEY`) | list or mapping |
 | `annotations` | `--annotation` (repeated; null value → bare `KEY`) | list or mapping |
+| `environment` | `-e` (repeated; null value → bare `KEY`, i.e. host passthrough) | list or mapping |
 | `pull_policy` | `--pull` (`if_not_present` → `missing`, rest verbatim) | enum: `always`/`never`/`missing`/`if_not_present` |
 | `ulimits` | `--ulimit` (`name=value` or `name=soft:hard`) | mapping, see below |
 
@@ -365,12 +366,6 @@ slot (`architecture/glossary.md`).
   the same Docker shell-form `ENTRYPOINT` semantic, not a
   compose2pod-specific limitation. Use a list (exec-form) entrypoint, or
   none, if the override needs to actually run.
-- **`environment`:** list (`- KEY=value`, `- KEY`) or mapping (`KEY: value`,
-  `KEY:`) — the same shape rule as the registry's map-shaped keys. A null
-  mapping value means "pass `KEY` through from the host", emitted as a bare
-  `-e KEY`, same as the list form `- KEY`. A boolean value (`DEBUG: true`)
-  is normalized like Docker: `-e DEBUG=true`, not the Python repr `-e
-  DEBUG=True`.
 - **`env_file`:** a string or list of strings. Each resolved path passes
   through `--project-dir` when relative, then is emitted as `--env-file`.
 - **`tmpfs`:** a string or list of strings, each `<path>` or
@@ -877,7 +872,7 @@ truth if this enumeration ever appears to drift:
 
 - **Structural fields:** `image` (only when the service has no `build`
   override — otherwise the CI image is used, not the compose value),
-  `command`, `entrypoint`, `environment`, `env_file`, `volumes`, `tmpfs`,
+  `command`, `entrypoint`, `env_file`, `volumes`, `tmpfs`,
   the healthcheck `test` command, and the pod-level
   `dns`/`dns_search`/`dns_opt`/`sysctls`/`extra_hosts` values.
 - **Registry fields** whose spec wraps its value in `Expand` — every

compose2pod/emit.py

@@ -10,7 +10,7 @@
 from compose2pod.exceptions import UnsupportedComposeError
 from compose2pod.graph import depends_on, hostnames, startup_order
 from compose2pod.healthcheck import health_cmd, interval_seconds
-from compose2pod.keys import SERVICE_KEYS, Expand, Token, key_value_pairs
+from compose2pod.keys import SERVICE_KEYS, Expand, Token
 from compose2pod.parsing import validate
 from compose2pod.pod import pod_create_flags
 from compose2pod.resources import deploy_resource_flags
@@ -69,12 +69,9 @@ def _health_flags(healthcheck: dict[str, Any]) -> list[Token]:
     return flags
 
 
-def _env_flags(svc: dict[str, Any], project_dir: str) -> list[Token]:
-    """-e and --env-file flag tokens."""
+def _env_file_flags(svc: dict[str, Any], project_dir: str) -> list[Token]:
+    """--env-file flag tokens. `environment` is a SERVICE_KEYS registry key (_map("-e"))."""
     flags: list[Token] = []
-    # A null environment value means "pass KEY through from the host" (bare `-e KEY`).
-    for pair in key_value_pairs(svc.get("environment") or {}):
-        flags += ["-e", Expand(value=str(pair))]
     env_files = svc.get("env_file") or []
     if isinstance(env_files, str):
         env_files = [env_files]
@@ -109,7 +106,7 @@ def _volume_flags(svc: dict[str, Any], project_dir: str) -> list[Token]:
 def run_flags(name: str, svc: dict[str, Any], pod: str, project_dir: str) -> list[Token]:
     """Flag tokens (unquoted) for `podman run` of one service."""
     flags: list[Token] = ["--pod", pod, "--name", f"{pod}-{name}"]
-    flags += _env_flags(svc, project_dir)
+    flags += _env_file_flags(svc, project_dir)
     flags += _volume_flags(svc, project_dir)
     flags += _health_flags(svc.get("healthcheck") or {})
     for key, spec in SERVICE_KEYS.items():

compose2pod/extends.py

@@ -3,15 +3,15 @@
 from typing import Any
 
 from compose2pod.exceptions import UnsupportedComposeError
-from compose2pod.keys import SERVICE_KEYS, as_list, pairs_to_mapping, split_extra_host
+from compose2pod.keys import SERVICE_KEYS, as_list, split_extra_host
 
 
 # Merge policy for keys with a SERVICE_KEYS KeySpec comes from spec.merge (see
 # _merge below); these two sets cover only the remaining structural keys, which
 # have no KeySpec. Both categories obey one rule: a merge may normalize a value
 # only through a form that key actually has, so it can never accept a shape the
 # gate would reject standalone.
-_STRUCTURAL_MERGE_KEYS = {"environment", "extra_hosts", "healthcheck", "depends_on"}
+_STRUCTURAL_MERGE_KEYS = {"extra_hosts", "healthcheck", "depends_on"}
 _STRUCTURAL_CONCAT_KEYS = {"secrets", "configs", "volumes", "tmpfs", "env_file"}
 
 # The only concat keys Compose gives a bare-string form. The gate accepts a
@@ -90,16 +90,17 @@ def _as_mapping(name: str, key: str, value: Any) -> dict[str, Any]:  # noqa: ANN
     """Normalize a structural mapping-merge key's value to a mapping.
 
     List form is accepted for exactly the keys Compose defines one for --
-    `environment`, `extra_hosts`, `depends_on` -- each through the normalizer
-    that key's own list form actually needs. `healthcheck` has no list form, so
-    a list is refused rather than coerced: a merge must not accept a shape the
-    gate would reject standalone (see `_merge`).
+    `extra_hosts`, `depends_on` -- each through the normalizer that key's own
+    list form actually needs. `environment` used to be handled here too, but
+    it is now a `SERVICE_KEYS` registry key (`_map("-e")`) whose own
+    `merge=_merge_map` branch in `_merge` wins first, so this function never
+    sees it. `healthcheck` has no list form, so a list is refused rather than
+    coerced: a merge must not accept a shape the gate would reject standalone
+    (see `_merge`).
     """
     if isinstance(value, dict):
         return value
     if isinstance(value, list):
-        if key == "environment":
-            return pairs_to_mapping(name, key, value)
         if key == "extra_hosts":
             return _extra_hosts_to_mapping(name, value)
         if key == "depends_on":

compose2pod/keys.py

@@ -342,6 +342,7 @@ def _emit_ulimits(value: Any) -> list[Token]:  # noqa: ANN401 - Compose values a
 
 
 SERVICE_KEYS: dict[str, KeySpec] = {
+    "environment": _map("-e"),
     "user": _scalar("--user"),
     "working_dir": _scalar("--workdir"),
     "platform": _scalar("--platform"),
@@ -388,7 +389,7 @@ def _emit_ulimits(value: Any) -> list[Token]:  # noqa: ANN401 - Compose values a
     "build",
     "command",
     "entrypoint",
-    "environment",
+    # "environment" removed — now a SERVICE_KEYS registry key (_map("-e")).
     "env_file",
     "volumes",
     "tmpfs",

compose2pod/parsing.py

@@ -493,12 +493,6 @@ def _validate_tmpfs(name: str, svc: dict[str, Any]) -> None:
     _validate_string_or_string_list(name, "tmpfs", svc.get("tmpfs"))
 
 
-def _validate_environment(name: str, svc: dict[str, Any]) -> None:
-    """Check environment is a list or mapping (a bare string would be walked as .items())."""
-    if svc.get("environment") is not None:
-        validate_map(name, "environment", svc["environment"])
-
-
 def _validate_env_file(name: str, svc: dict[str, Any]) -> None:
     """Check env_file is a string or list of strings (emit iterates it)."""
     _validate_string_or_string_list(name, "env_file", svc.get("env_file"))
@@ -553,7 +547,6 @@ def _validate_service(name: str, svc: Any) -> list[str]:  # noqa: ANN401 - Compo
     _validate_entrypoint(name, svc)
     _validate_command(name, svc)
     _validate_tmpfs(name, svc)
-    _validate_environment(name, svc)
     _validate_env_file(name, svc)
     validate_deploy(name, svc)
     validate_pod_options(name, svc)

planning/changes/2026-07-15.17-environment-into-registry.md

@@ -0,0 +1,97 @@
+---
+summary: Move the `environment` service key into the SERVICE_KEYS registry as `_map("-e")`, deleting its hand-rolled validate/emit/merge across parsing/emit/extends so it gains the single-spec locality (and drift-immunity) the 29 registry keys already have.
+---
+
+# Design: move `environment` into the service-key registry
+
+## Summary
+
+`environment` is handled outside `SERVICE_KEYS` today — its validate lives in
+`parsing._validate_environment`, its emit in the `-e` branch of `emit._env_flags`,
+its merge in `extends._STRUCTURAL_MERGE_KEYS` — even though it is provably
+`_map("-e")`: the same `validate_map`, the same `["-e", Expand(str(pair))]` emit
+loop, and the same `_merge_map` its registry twins `labels`/`annotations` already
+use. This change adds `"environment": _map("-e")` to `SERVICE_KEYS` and deletes
+the three hand-rolled halves, giving `environment` one spec = validate+emit+merge
+in one place. Behavior-preserving.
+
+## Motivation
+
+`environment` re-implements a registry abstraction the code already trusts for 29
+keys, and the hand-rolling carries the exact drift hazard the registry retires:
+its validate (`parsing.py`, `validate_map`) and its merge normalizer
+(`extends._as_mapping`) live in different modules with no binding, so the
+`extends` structural branch must re-derive the accepted grammar by hand to avoid
+laundering a shape the gate would reject (`extends.py:83-119`). The registry
+branch closes this by construction — it runs `spec.validate` on each side before
+`spec.merge` (`extends.py:145-156`). Moving `environment` in inherits that
+immunity for free. This is the narrow move licensed as examined-and-in-scope by
+`decisions/2026-07-12-reject-structural-key-registry.md` (the reopen note): a key
+that shares one uniform shape, not a structural-key registry.
+
+## Design
+
+Four source edits:
+
+- **`keys.py`** — add `"environment": _map("-e")` to `SERVICE_KEYS`; remove
+  `"environment"` from `STRUCTURAL_KEYS`.
+- **`parsing.py`** — delete `_validate_environment` and its call in
+  `_validate_service`. `environment` is now validated by the existing
+  `SERVICE_KEYS` loop (`spec.validate`, `parsing.py:560-562`). The old
+  `if ... is not None` guard was already dead: `_reject_null_values` refuses a
+  null `environment` earlier in the same function.
+- **`emit.py`** — rename `_env_flags` → `_env_file_flags` and drop its `-e`
+  loop, keeping only the `--env-file` emission; update the `run_flags` call site.
+  `environment`'s `-e` tokens now come from the `SERVICE_KEYS` loop.
+- **`extends.py`** — remove `"environment"` from `_STRUCTURAL_MERGE_KEYS`; it
+  now merges via `SERVICE_KEYS["environment"].merge`.
+
+Invariants held:
+
+- **Gate accept-list**: `SUPPORTED_SERVICE_KEYS = set(SERVICE_KEYS) | STRUCTURAL_KEYS`
+  — `environment` only switches sides; the union is identical, so no key's
+  accept/reject status changes.
+- **Emit**: `-e KEY=val` tokens are byte-identical. The `-e` flags move *after*
+  `--env-file` in the generated `podman run` line, but podman's env precedence is
+  by source, not command-line order — `--env` overrides `--env-file` regardless
+  (stated in `podman-run.1`'s ENVIRONMENT precedence list) — so the container
+  environment is unchanged, and Compose's "environment overrides env_file" still
+  holds.
+- **Validate**: both the old and new paths call `validate_map`; the refusal
+  message for a malformed `environment` is unchanged.
+
+## Non-goals
+
+- Moving `tmpfs`/`env_file`/`volumes` — `tmpfs` needs a bespoke validator
+  (scalar-or-list vs `_list`'s list-only) and `env_file`/`volumes` need
+  `project_dir`, which would force widening `KeySpec.emit`. Out of scope here.
+- Any change to `SERVICE_KEYS.emit`'s signature — `environment` fits
+  `emit(value)` as-is.
+
+## Testing
+
+`just test-ci` at 100% coverage, `just lint-ci` clean, `just check-planning`.
+
+- `tests/test_keys.py` — `SERVICE_KEYS` count +1, `STRUCTURAL_KEYS` −1, union
+  unchanged, `SERVICE_KEYS`/`STRUCTURAL_KEYS` still disjoint; the parametrized
+  merge test now asserts `environment` carries `merge=_merge_map`.
+- `tests/test_emit.py` — the positional `-e` assertions (`flags[4:6]`, etc.)
+  shift; rewrite them to locate the `-e` pair rather than a fixed index, and keep
+  the `env_file`-only case (now `--env-file` at the front of the env flags).
+- `tests/test_parsing.py` — malformed `environment` still refused with the same
+  `validate_map` message.
+- `tests/test_extends.py` — add a case proving the registry branch now validates
+  each side before merging (an extends chain whose individual side has a
+  malformed `environment` is refused, matching `labels`/`annotations`), plus the
+  existing valid list-form/dict-form `environment` merges re-asserted unchanged.
+- Conformance + integration suites — green, no behavior change.
+
+## Risk
+
+- **A test constructs an extends chain with a per-side-malformed `environment`
+  that was previously accepted post-merge** (low × med): now refused earlier by
+  the registry branch. This is the intended drift-close (identical to
+  `labels`/`annotations` today) — grep `test_extends.py` first; if such a case
+  exists it is re-asserted as a refusal, not a regression.
+- **Missed positional `-e` assertion in `test_emit.py`** (low × low): caught by
+  `just test-ci` before push.

tests/test_emit.py

@@ -28,10 +28,11 @@ class TestRunFlags:
     def test_db_flags(self, chats_compose: dict) -> None:
         flags = run_flags("db", chats_compose["services"]["db"], "test-pod", "/builds/chats")
         assert flags[:4] == ["--pod", "test-pod", "--name", "test-pod-db"]
-        assert flags[4:6] == ["-e", Expand(value="POSTGRES_PASSWORD=password")]
-        assert flags[6:8] == ["--health-cmd", Expand(value="pg_isready -U database -d database")]
-        assert flags[8:10] == ["--health-timeout", "5s"]
-        assert flags[10:12] == ["--health-retries", "15"]  # fix #2
+        # environment is a registry key now, emitted after the healthcheck flags.
+        assert flags[4:6] == ["--health-cmd", Expand(value="pg_isready -U database -d database")]
+        assert flags[6:8] == ["--health-timeout", "5s"]
+        assert flags[8:10] == ["--health-retries", "15"]  # fix #2
+        assert flags[10:12] == ["-e", Expand(value="POSTGRES_PASSWORD=password")]
 
     def test_start_period_is_passed_through(self) -> None:
         svc = {"image": "x", "healthcheck": {"test": "true", "start_period": "30s"}}

tests/test_extends.py

@@ -224,7 +224,10 @@ def test_incompatible_mapping_form_is_refused(self) -> None:
                 "web": {"extends": {"service": "base"}, "environment": "NOT_A_MAP"},
             }
         }
-        with pytest.raises(UnsupportedComposeError, match="cannot merge 'environment' across incompatible forms"):
+        # environment is now a registry key: the merge validates each side first
+        # (like labels/annotations), so a non-mapping local is refused by
+        # validate_map before the structural "cannot merge" path is reached.
+        with pytest.raises(UnsupportedComposeError, match="'environment' must be a list or mapping"):
             resolve_extends(doc)
 
     def test_diamond_inheritance_resolves_base_once(self) -> None: