feat(translation): list known keys in TranslationMap KeyError (#768)

* feat(translation): list known keys in TranslationMap KeyError messages

When `to_upstream` / `to_adcp` miss, surface the full set of known keys
in the exception so adopters debugging a typo or stale mapping see the
fix without instrumenting the call site. dx-expert flagged this as the
one outstanding nit from the #453 triage; the rest of that issue is
resolved by #464.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* ci: skip merge commits from remote-tracking refs

`git merge origin/main` produces "Merge remote-tracking branch 'origin/main' …",
which the conventional-commits skip regex didn't match — only `Merge branch
'<name>'` was covered. Validator then flagged the merge commit as a malformed
conventional commit and failed the check.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bokelley

.github/workflows/ci.yml

@@ -114,12 +114,14 @@ jobs:
           # Check each commit since the base
           echo "Validating commits since $BASE_SHA..."
           git log --format="%H %s" $BASE_SHA..HEAD | while read sha message; do
-            # Skip merge commits. Two GitHub-created shapes:
+            # Skip merge commits. Three GitHub/git-created shapes:
             # - "Merge <sha> into <sha>" — the merge-queue API path
             #   (clicking "Update branch" on a PR)
             # - "Merge branch '<name>' [into <name>]" — `gh pr update-branch`
-            #   and `git merge` defaults
-            if echo "$message" | grep -qE "^Merge ([0-9a-f]+ into [0-9a-f]+|branch '[^']+')"; then
+            #   and `git merge <local-branch>` defaults
+            # - "Merge remote-tracking branch '<name>' [into <name>]" —
+            #   `git merge origin/<branch>` default
+            if echo "$message" | grep -qE "^Merge ([0-9a-f]+ into [0-9a-f]+|(remote-tracking )?branch '[^']+')"; then
               echo "⊙ Skipping merge commit: $sha"
               continue
             fi

src/adcp/decisioning/translation.py

@@ -81,7 +81,8 @@ def to_upstream(self, adcp_key: A) -> U:
             return self._forward[adcp_key]
         if self._default_upstream is not None:
             return self._default_upstream
-        raise KeyError(f"unknown AdCP key: {adcp_key!r}")
+        known = sorted(self._forward.keys(), key=repr)
+        raise KeyError(f"unknown AdCP key {adcp_key!r}; known keys: {known!r}")
 
     def to_adcp(self, upstream_key: U) -> A:
         """Translate an upstream platform value back to the AdCP wire value.
@@ -93,7 +94,8 @@ def to_adcp(self, upstream_key: U) -> A:
             return self._reverse[upstream_key]
         if self._default_adcp is not None:
             return self._default_adcp
-        raise KeyError(f"unknown upstream key: {upstream_key!r}")
+        known = sorted(self._reverse.keys(), key=repr)
+        raise KeyError(f"unknown upstream key {upstream_key!r}; known keys: {known!r}")
 
     def has_adcp(self, value: object) -> bool:
         """True when ``value`` is a known AdCP-side key."""

tests/test_upstream_helpers.py

@@ -58,12 +58,22 @@ def test_to_adcp_returns_a_side(self) -> None:
         assert self.channel_map.to_adcp("audio") == "streaming_audio"
 
     def test_to_upstream_raises_on_unknown(self) -> None:
-        with pytest.raises(KeyError):
+        with pytest.raises(KeyError) as exc_info:
             self.channel_map.to_upstream("unknown")
+        message = str(exc_info.value)
+        assert "'unknown'" in message
+        assert "'olv'" in message
+        assert "'ctv'" in message
+        assert "'display'" in message
+        assert "'streaming_audio'" in message
 
     def test_to_adcp_raises_on_unknown(self) -> None:
-        with pytest.raises(KeyError):
+        with pytest.raises(KeyError) as exc_info:
             self.channel_map.to_adcp("unknown_upstream")
+        message = str(exc_info.value)
+        assert "'unknown_upstream'" in message
+        assert "'video'" in message
+        assert "'audio'" in message
 
     def test_has_adcp(self) -> None:
         assert self.channel_map.has_adcp("olv") is True