feat(reporting): add buyer client helpers and a tracker for reporting subscriptions

docs/reliable-reporting-service.md

@@ -334,6 +334,18 @@ and the `subscription_coverage[]` exceptions and gaps. It returns
 they feed `evaluate_reporting_ledger` and the consumer-status planner as they
 are.
 
+`ReportingSubscriptionTracker` keeps those records for you. Register through
+`tracker.sync(...)` so every version's configuration is kept (the readback
+keeps only the current one), record what `list_accounts` shows with
+`tracker.observe_account(...)`, and pass each `principal.changed` payload to
+`tracker.handle_notification(...)`; it re-reads `get_principal` and folds
+`accounts_unauthorized[]` into the grant history.
+`tracker.expected_periods(subscription_id, account_id, buys=..., now=...,
+coverage=...)` then returns what the seller owes. A withheld period carries no
+`expected_at`, so it is never claimed missing while authority is absent.
+`sync_reporting_subscriptions`, `read_reporting_subscriptions` and
+`load_subscription_coverage` are the underlying client helpers.
+
 **Seller.** Opt in on the principal runtime and link it to the engine. Without
 `reporting_subscriptions=`, `PrincipalService` rejects the section with
 `UNSUPPORTED_FEATURE`, as the spec requires for an unsupported section.

src/adcp/reporting/subscriptions/__init__.py

@@ -15,6 +15,9 @@
 * :func:`apply_reporting_subscriptions` -- validation and versioning of the
   ``sync_principal`` section, used by ``PrincipalService`` when it is given
   ``reporting_subscriptions=`` options.
+* :class:`ReportingSubscriptionTracker` and :func:`sync_reporting_subscriptions`
+  -- the buyer's client side: register, read back, refresh on
+  ``principal.changed``, and compute expected periods from its own records.
 * :class:`ReportingSubscriptionEngine` -- the seller runtime: host hooks,
   lost authority, exceptions, ``subscription_coverage[]`` and owed periods.
 """
@@ -30,6 +33,16 @@
     subscription_capabilities,
     with_subscription_dimensions,
 )
+from adcp.reporting.subscriptions.consumer import (
+    REPORTING_SUBSCRIPTION_CHANGED,
+    ReportingSubscriptionClientError,
+    ReportingSubscriptionReadback,
+    ReportingSubscriptionTracker,
+    is_subscription_change,
+    load_subscription_coverage,
+    read_reporting_subscriptions,
+    sync_reporting_subscriptions,
+)
 from adcp.reporting.subscriptions.coverage import (
     AccountTimezoneChange,
     ExpectedSubscriptionPeriod,
@@ -78,6 +91,14 @@
 )
 
 __all__ = [
+    "REPORTING_SUBSCRIPTION_CHANGED",
+    "ReportingSubscriptionClientError",
+    "ReportingSubscriptionReadback",
+    "ReportingSubscriptionTracker",
+    "is_subscription_change",
+    "load_subscription_coverage",
+    "read_reporting_subscriptions",
+    "sync_reporting_subscriptions",
     "AccountDeliveryConfig",
     "AuthorizedAccount",
     "AuthorizedAccountPage",