fix(webhooks): reject unknown AdCP status in create_a2a_webhook_payload (#605)

The builder previously fell back to ``TASK_STATE_UNSPECIFIED`` when the
caller's status didn't match the AdCP→A2A mapping table. The wire
normalizer then rewrote that to the literal string ``"unspecified"``,
which is not a valid A2A v0.3 ``TaskState`` (the spec enum is submitted
| working | input-required | completed | canceled | failed | rejected
| auth-required | unknown). Buyer receivers validating against the
schema reject the webhook — silent wire-level breakage.

Raise ``ValueError`` at the builder boundary instead. The AdCP→A2A
mapping is closed, so an unknown value is always a caller bug; failing
loud beats producing a payload buyers will reject mid-delivery.

Closes #603.

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

Author: bokelley

src/adcp/webhooks.py

@@ -574,7 +574,18 @@ def create_a2a_webhook_payload(
         # Tolerate the hyphenated form servers may echo back.
         "input-required": pb.TaskState.TASK_STATE_INPUT_REQUIRED,
     }
-    task_state_enum = adcp_to_task_state.get(status_value, pb.TaskState.TASK_STATE_UNSPECIFIED)
+    if status_value not in adcp_to_task_state:
+        # Falling back to TASK_STATE_UNSPECIFIED would normalize to the
+        # string ``"unspecified"`` on the wire, which is not a valid A2A
+        # v0.3 ``TaskState`` — buyer receivers validating against the
+        # spec reject the webhook. Fail loud at the builder boundary
+        # instead of producing a silently-broken envelope.
+        raise ValueError(
+            f"Unknown AdCP task status {status_value!r}; expected one of "
+            f"{sorted(set(adcp_to_task_state))}. AdCP→A2A status mapping is "
+            "closed — an unknown value indicates a caller bug."
+        )
+    task_state_enum = adcp_to_task_state[status_value]
 
     # Build parts for the message/artifact.
     parts: list[pb.Part] = []

tests/test_webhooks_to_wire_dict.py

@@ -127,3 +127,17 @@ def test_unsupported_type_raises_type_error() -> None:
     """Silent fallthrough would mask integration bugs — fail loud."""
     with pytest.raises(TypeError, match="Unsupported webhook payload type"):
         to_wire_dict("not a payload")  # type: ignore[arg-type]
+
+
+def test_a2a_unknown_status_raises_value_error() -> None:
+    """Unknown AdCP status must fail at the builder, not produce an
+    invalid-on-the-wire ``"unspecified"`` TaskState that buyer receivers
+    reject. (Issue #603.)
+    """
+    with pytest.raises(ValueError, match="Unknown AdCP task status"):
+        create_a2a_webhook_payload(
+            task_id="task_123",
+            status="not-a-real-status",  # type: ignore[arg-type]
+            context_id="ctx_456",
+            result={"media_buy_id": "mb_1"},
+        )