docs(planning): fix stale merge signature and structural-key count in design doc

Final review caught two drift spots in the design file: illustrative code
snippets still showed the 2-arg merge(base, local) signature superseded
during implementation by the 4-arg (name, key, base, local) form, and the
structural-key count said 8 instead of 9.

Author: lesnik512

planning/changes/2026-07-13.05-derive-extends-merge-policy-from-keyspec.md

@@ -11,7 +11,7 @@ Add a `merge: Callable[[Any, Any], Any] | None` field to `KeySpec`. The
 respectively), so every `SERVICE_KEYS` entry built through them gets extends
 support for free. `extends.py`'s `_merge` looks up `SERVICE_KEYS[key].merge`
 first, falling back to a shrunk, structural-only `_MERGE_KEYS`/`_CONCAT_KEYS` for
-the 8 keys that still have no `KeySpec`. A new `_pairs_to_mapping` in `keys.py`
+the 9 keys that still have no `KeySpec`. A new `_pairs_to_mapping` in `keys.py`
 (the inverse of `_key_value_pairs`) backs the map-merge callable and, as a side
 effect, fixes list-form `labels`/`annotations` merging — currently untested and
 currently broken.
@@ -46,7 +46,7 @@ for `labels`/`annotations` (that's what `_key_value_pairs` exists for), but
 class KeySpec:
     validate: Callable[[str, str, Any], None]
     emit: Callable[[Any], list[Token]]
-    merge: Callable[[Any, Any], Any] | None = None
+    merge: Callable[[str, str, Any, Any], Any] | None = None
 ```
 
 `_list()` and `_map()` set it automatically — no opt-in argument, so a future
@@ -62,11 +62,14 @@ def _map(flag: str) -> KeySpec:
     return KeySpec(validate=_validate_map, emit=emit, merge=_merge_map)
 ```
 
-`_concat_list(base, local)` normalizes both sides via the existing
+`_concat_list(name, key, base, local)` normalizes both sides via the existing
 list-or-str handling (moved from `extends._as_list`) and concatenates.
-`_merge_map(base, local)` normalizes both sides via the new `_pairs_to_mapping`
-(list-or-dict → dict, the inverse of `_key_value_pairs`, living beside it in
-`keys.py`) and dict-merges, local winning. `ulimits`'s bespoke `KeySpec`
+`_merge_map(name, key, base, local)` normalizes both sides via the new
+`_pairs_to_mapping` (list-or-dict → dict, the inverse of `_key_value_pairs`,
+living beside it in `keys.py`) and dict-merges, local winning. `merge`'s
+`(name, key, ...)` prefix mirrors `validate`'s signature, so a merge callable
+can raise the same service/key-named `UnsupportedComposeError` as validation
+does. `ulimits`'s bespoke `KeySpec`
 (`keys.py:191`) sets `merge=_merge_map` explicitly since it bypasses the `_map()`
 factory.
 
@@ -78,7 +81,7 @@ def _merge(base: dict[str, Any], local: dict[str, Any], name: str) -> dict[str,
     for key, local_val in local.items():
         spec = SERVICE_KEYS.get(key)
         if key in base and spec is not None and spec.merge is not None:
-            merged[key] = spec.merge(base[key], local_val)
+            merged[key] = spec.merge(name, key, base[key], local_val)
         elif key in base and key in _MERGE_KEYS:      # structural keys only
             ...
         elif key in base and key in _CONCAT_KEYS:      # structural keys only
@@ -88,7 +91,7 @@ def _merge(base: dict[str, Any], local: dict[str, Any], name: str) -> dict[str,
     return merged
 ```
 
-`_MERGE_KEYS`/`_CONCAT_KEYS` shrink to the 8 keys with no `KeySpec`:
+`_MERGE_KEYS`/`_CONCAT_KEYS` shrink to the 9 keys with no `KeySpec`:
 `_MERGE_KEYS = {"environment", "extra_hosts", "healthcheck", "depends_on"}`,
 `_CONCAT_KEYS = {"secrets", "configs", "volumes", "tmpfs", "env_file"}` — their
 `_as_mapping`/`_as_list` handling is unchanged. A one-line comment marks these
@@ -102,7 +105,7 @@ and shape-derived.
 
 ## Non-goals
 
-- Unifying the 8 structural keys' merge policy — deferred; would conflate this
+- Unifying the 9 structural keys' merge policy — deferred; would conflate this
   change with candidate #3 of the 2026-07-13 architecture review (owning
   module per structural key), and `decisions/2026-07-12-reject-structural-key-registry.md`
   already rejects a uniform structural registry on shape-heterogeneity grounds