feat(reporting): add the buyer write facade and guard raw sync_principal

src/adcp/client.py

@@ -26,6 +26,8 @@
     import httpx
     from mcp import ClientSession
 
+    from adcp.reporting.subscriptions.facade import ReportingClient
+
 from adcp._null_clear import preserve_explicit_nulls
 from adcp._response_limit import (
     DEFAULT_MAX_RESPONSE_BYTES,
@@ -962,6 +964,7 @@ def __init__(
         self._raise_account_errors_explicit = raise_account_errors is not None
         self.raise_account_errors = raise_account_errors is True
         self.accounts = AccountRegistry(self, account_storage)
+        self._reporting: Any | None = None
         self.webhook_url_template = webhook_url_template
         self.webhook_secret = webhook_secret
         self.allow_unauthenticated_webhooks = allow_unauthenticated_webhooks
@@ -1322,6 +1325,18 @@ def get_server_version(self) -> str | None:
         """
         return self._server_version
 
+    @property
+    def reporting(self) -> ReportingClient:
+        """Patch-shaped reporting-subscription writes: ``subscribe``, ``unsubscribe``, ...
+
+        See :class:`adcp.reporting.subscriptions.facade.ReportingClient`.
+        """
+        if self._reporting is None:
+            from adcp.reporting.subscriptions.facade import ReportingClient
+
+            self._reporting = ReportingClient(self)
+        return cast("ReportingClient", self._reporting)
+
     @property
     def context_id(self) -> str | None:
         """Current A2A conversation context_id.
@@ -4434,9 +4449,37 @@ async def sync_principal(
         self,
         request: SyncPrincipalRequest,
         *,
+        allow_deactivation: bool = False,
+        allow_revocation: bool = False,
         options: TaskOptions | None = None,
     ) -> TaskResult[SyncPrincipalResponse]:
-        """Declaratively replace selected authenticated-principal configuration."""
+        """Declaratively replace selected authenticated-principal configuration.
+
+        Each section is complete desired state: a subscription missing from
+        ``reporting_subscriptions`` is deactivated, and a destination missing
+        from ``reporting_destinations`` is revoked for every account. To add
+        or change one subscription, use ``client.reporting.subscribe()``.
+
+        A write carrying either section first reads the principal and is
+        refused before dispatch (``ReportingSubscriptionError``, code
+        ``SUBSCRIPTION_WOULD_DEACTIVATE`` or ``DESTINATION_WOULD_REVOKE``) if it
+        would deactivate an active subscription or revoke a destination by
+        omission. Pass ``allow_deactivation=True`` / ``allow_revocation=True``
+        to proceed. Sending ``active: false`` is always allowed.
+        """
+        from adcp.reporting.subscriptions.facade import guard_sync_principal
+
+        await guard_sync_principal(
+            self,
+            request,
+            allow_deactivation=allow_deactivation,
+            allow_revocation=allow_revocation,
+        )
+        return await self._sync_principal_unguarded(request)
+
+    async def _sync_principal_unguarded(
+        self, request: SyncPrincipalRequest
+    ) -> TaskResult[SyncPrincipalResponse]:
         return cast(
             TaskResult[SyncPrincipalResponse],
             await self._execute_typed_task("sync_principal", request, SyncPrincipalResponse),

src/adcp/reporting/subscriptions/__init__.py

@@ -79,6 +79,12 @@
     SubscriptionPlanResult,
     subscription_obligation_id,
 )
+from adcp.reporting.subscriptions.facade import (
+    PreviewResult,
+    ReportingClient,
+    SubscribeResult,
+    guard_sync_principal,
+)
 from adcp.reporting.subscriptions.registry import (
     ReportingSubscriptionValidationError,
     apply_reporting_subscriptions,
@@ -103,6 +109,10 @@
 )
 
 __all__ = [
+    "PreviewResult",
+    "ReportingClient",
+    "SubscribeResult",
+    "guard_sync_principal",
     "FrozenOwedSet",
     "SubscriptionObligationPlanner",
     "SubscriptionPlanResult",

src/adcp/reporting/subscriptions/consumer.py

@@ -25,7 +25,7 @@
 from collections.abc import Mapping, Sequence
 from dataclasses import dataclass, field
 from datetime import datetime, timedelta
-from typing import Any, Protocol
+from typing import Any, Literal, Protocol
 from uuid import uuid4
 
 from adcp.exceptions import ADCPError, RecoveryLiteral, _normalize_recovery
@@ -95,6 +95,7 @@ def __init__(
         *,
         code: str | None = None,
         recovery: RecoveryLiteral | None = None,
+        dispatched: Literal[False] | None = None,
         would_deactivate: Sequence[str] = (),
         readback: ReportingSubscriptionReadback | None = None,
     ) -> None:
@@ -107,6 +108,8 @@ def __init__(
                 self.dispatched = False
         else:
             self.recovery = recovery or _code_recovery(code)
+        if dispatched is False:
+            self.dispatched = False
         self.would_deactivate = tuple(would_deactivate)
         self.readback = readback