Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 37 additions & 24 deletions docs/reporting-status-notifications.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,10 +22,11 @@ status store, pure projector, due sweeper, C outbox/HTTP worker, signing and
subscription resolvers, and a mounted `ReportingStatusNotificationHandler`.
`scheduled=True` is the adopter's commitment to supervise all worker phases;
the SDK does not start them implicitly. Capability checks validate schema,
baseline, policy agreement, the actual `get_reporting_status` tool, and signing
material for validated `readiness_subscriptions`. An empty subscription lookup
does not prove signing readiness. Memory implementations are conformance tools
and never advertise durability.
baseline, policy agreement, the actual `get_reporting_status` tool, and delivery
configuration for every active subscription. Optional
`readiness_subscriptions` remain supported as additional signing probes, but an
external subscriber is not a prerequisite for capability discovery. Memory
implementations are conformance tools and never advertise durability.

Activity storage is optional for status delivery. If the C HTTP worker has an
activity recorder attached, readiness also validates that recorder's C tables
Expand All @@ -51,25 +52,33 @@ for lifecycle work as well as capability proof; incomplete results refuse work
before any side effects.

Resolve all three fields from one complete deployment-wide transaction or
configuration revision, including the account enumeration and its signing
readiness probes. Request body, `ext` and arbitrary request context are never
resolver inputs. A request-scoped account or convenient single-account sample
cannot prove deployment-wide readiness. An incomplete, empty or unavailable
surface cannot advertise status notifications. Every listed account must be
migrated, baselined and structurally ready; one unready account suppresses the
global claim. An empty `readiness_subscriptions=()` is valid for strict type
checking but fails readiness at runtime. Every account needs a validated signing
probe, even when it has no active subscribers.
configuration revision. Request body, `ext` and arbitrary request context are
never resolver inputs. A request-scoped account or convenient single-account
sample cannot prove deployment-wide readiness. An incomplete or unavailable
surface cannot advertise status notifications. A complete empty account surface
is valid and lets a deployment advertise before its first account or subscriber
is enrolled. Every listed account must be migrated, baselined and structurally
ready; one unready account suppresses the global claim. Every active subscription
and every supplied readiness probe must retain valid authorization,
proof-of-control, signing and delivery configuration. Empty
`readiness_subscriptions=()` is valid and does not weaken those checks.

Readiness is structural. A valid waiver, an outage, incomplete coverage and
other current business health never disable a ready feature. Explicit claims
with missing components raise secret-free configuration errors; omission stays
omission. Calling `support.advertised_notifications()` explicitly opts into
automatic advertisement when ready. Generated reporting capability models emit
omission. The decisioning handler calls `support.advertised_notifications()`
for each capability request and projects the result only when that request's
`webhook_signing.supported` is true. Generated reporting capability models emit
only explicitly set optional task, notification and tier fields. Required
`configuration_task` and `status_task` declarations must also be supplied by the
adopter; do not rely on generated defaults to mount handlers. Other claimed
tasks must have real overrides and appear in `tools/list` and MCP/A2A dispatch.
`configuration_task` declarations must be supplied by the adopter. Ready status
support projects its mounted `status_task` with the notification claim. Other
claimed tasks must have real overrides and appear in `tools/list` and MCP/A2A
dispatch.

This bootstrap rule does not enroll a receiver. Consumers still require the
signed-webhook capability and their full notification set before registering
doorbells. Authorization, proof-of-control, signing-scope and delivery checks
run for every active subscription during readiness and again at delivery time.

`DecisioningPlatform` does not gain reporting task implementations from a
capability declaration. Compose real handlers, as in
Expand All @@ -81,29 +90,30 @@ participant. It checks types under `mypy --strict`.

### ESA decisioning setup

ESA upgrades to `adcp>=9.6.3`; no `adcp-reporting-storage` upgrade or wire-schema
ESA upgrades to `adcp>=10.0.0b19`; no `adcp-reporting-storage` upgrade or wire-schema
change is required for dynamic account resolution. Import the public surface
and support types from `adcp.reporting.outbox` and pass the support to ordinary
decisioning `serve()`. It binds its generated handler to the support
automatically; the adopter does not construct or mutate that handler.

The following composition assumes the real platform reporting handlers,
PostgreSQL store, worker, projector and sweeper are configured. The adopter's
`read_reporting_accounts_and_probes()` reads the complete deployment account IDs
and validated readiness subscriptions together in one transaction/revision;
it takes no request inputs and must fail if that complete read is unavailable.
`read_reporting_accounts()` reads the complete deployment account IDs in one
transaction/revision; it takes no request inputs and must fail if that complete
read is unavailable. Deployments with internal signing probes may return them in
the same snapshot.

```python
from adcp.decisioning import serve
from adcp.reporting.outbox import ReportingStatusAccountSurface, ReportingStatusSupport


async def account_surface() -> ReportingStatusAccountSurface:
account_ids, readiness_subscriptions = await read_reporting_accounts_and_probes()
account_ids = await read_reporting_accounts()
return ReportingStatusAccountSurface(
account_ids=tuple(account_ids),
account_surface_complete=True,
readiness_subscriptions=tuple(readiness_subscriptions),
readiness_subscriptions=(),
)


Expand All @@ -122,6 +132,9 @@ This ordinary `serve()` call mounts the handler; `scheduled=True` still requires
ESA to supervise lifecycle work. Capability checks resolve a fresh surface, so
adding an account requires no server restart. The global claim stays suppressed
until that account has been baselined and all readiness checks pass. The
complete empty surface advertises during bootstrap when webhook signing and the
durable lifecycle are ready. A newly enrolled active subscription is validated
on the next proof and on delivery. The
[custom-handler lifecycle example](../examples/reporting_status_notifications.py)
also accepts this resolver; omitting it adapts the supplied static account and
probe sequences to a constant async snapshot.
Expand Down
14 changes: 12 additions & 2 deletions src/adcp/decisioning/handler.py
Original file line number Diff line number Diff line change
Expand Up @@ -2438,7 +2438,7 @@ async def get_adcp_capabilities(
# truncate and flag *_complete: false rather than serve them whole.
bound_capability_domain_lists(response)

from adcp.reporting.outbox.status_support import validate_status_claims
from adcp.reporting.outbox.status_support import _project_ready_status_claims
from adcp.reporting.outbox.support import validate_activity_claims

reporting = getattr(self._platform, "_reliable_reporting_service", None)
Expand All @@ -2448,7 +2448,17 @@ async def get_adcp_capabilities(
adcp_version=context.resolved_adcp_version if context is not None else None,
)

await validate_status_claims(response, support=self._reporting_status, handler=self)
signing = response.get("webhook_signing", {})
signing_supported = isinstance(signing, dict) and signing.get("supported") is True
advertised_status: dict[str, str] = {}
if signing_supported and self._reporting_status is not None:
advertised_status = await self._reporting_status.advertised_notifications()
_project_ready_status_claims(
response,
advertised=advertised_status,
support=self._reporting_status,
handler=self,
)

await validate_activity_claims(
response,
Expand Down
113 changes: 88 additions & 25 deletions src/adcp/reporting/outbox/status_support.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,11 @@

logger = logging.getLogger(__name__)

_STATUS_NOTIFICATION_CLAIMS = {
"status_task": "get_reporting_status",
"status_notification": "reporting.status_changed",
}


@dataclass(frozen=True, kw_only=True)
class ReportingStatusAccountSurface:
Expand Down Expand Up @@ -107,21 +112,28 @@ async def account_ready(self, *, account_id: str) -> bool:
return await self._account_ready(account_id=account_id, surface=surface)

async def _account_ready(
self, *, account_id: str, surface: ReportingStatusAccountSurface
self,
*,
account_id: str,
surface: ReportingStatusAccountSurface,
queue_ready: bool = False,
) -> bool:
if not await self.queue_durable() or not await self.store.baseline_ready(
account_id=account_id
):
if not queue_ready and not await self.queue_durable():
return False
if not await self.store.baseline_ready(account_id=account_id):
return False
assert isinstance(self.store, ReportingDurableStatusStore)
if await self.store.managed_delivery_recorded(account_id=account_id):
return False # Managed expiry/reconciliation health ships with D.
subscriptions = await self.worker.subscriptions.list_active(
account_id=account_id, notification_type="reporting.status_changed"
)
probes = tuple(s for s in surface.readiness_subscriptions if s.account_id == account_id)
if not probes:
return False
probes: list[ReportingNotificationSubscription] = []
for subscription in surface.readiness_subscriptions:
if type(subscription) is not ReportingNotificationSubscription:
raise ReportingNotificationError("status_subscription_unready")
if subscription.account_id == account_id:
probes.append(subscription)
identities: set[str] = set()
for subscription in subscriptions:
if (
Expand Down Expand Up @@ -163,12 +175,19 @@ async def durable(self) -> bool:
return False
if (
not surface.account_surface_complete
or not surface.account_ids
or any(not account_id for account_id in surface.account_ids)
or not surface.readiness_subscriptions
or self.handler is None
):
return False
accounts = frozenset(surface.account_ids)
if any(
type(subscription) is not ReportingNotificationSubscription
or subscription.account_id not in accounts
for subscription in surface.readiness_subscriptions
):
raise ReportingNotificationError("status_subscription_unready")
if not await self.queue_durable():
return False
projection = getattr(self.handler, "reporting_status_handler", None)
if (
type(projection) is not ReportingStatusHandler
Expand All @@ -179,48 +198,92 @@ async def durable(self) -> bool:
not in {t["name"] for t in get_tools_for_handler(self.handler, _include_schemas=False)}
):
return False
return all(
[
await self._account_ready(account_id=a, surface=surface)
for a in sorted(set(surface.account_ids))
]
)
for account_id in sorted(set(surface.account_ids)):
if not await self._account_ready(
account_id=account_id,
surface=surface,
queue_ready=True,
):
return False
return True

async def advertised_notifications(self) -> dict[str, str]:
"""An explicit global claim, after checking the entire trusted surface."""
return (
{
"status_task": "get_reporting_status",
"status_notification": "reporting.status_changed",
}
if await self.durable()
else {}
)
return dict(_STATUS_NOTIFICATION_CLAIMS) if await self.durable() else {}


async def validate_status_claims(
response: dict[str, Any],
*,
support: ReportingStatusSupport | None,
handler: ADCPHandler[Any] | None = None,
) -> None:
claim = response.get("media_buy", {}).get("reporting_delivery", {}).get("status_notification")
if claim is None:
return
ready = support is not None and await support.durable()
_validate_ready_status_claims(
response,
support=support,
handler=handler,
ready=ready,
)


def _validate_ready_status_claims(
response: dict[str, Any],
*,
support: ReportingStatusSupport | None,
handler: ADCPHandler[Any] | None,
ready: bool,
) -> None:
claim = response.get("media_buy", {}).get("reporting_delivery", {}).get("status_notification")
if claim is None:
return
block = response.get("media_buy", {}).get("reporting_delivery", {})
signing = response.get("webhook_signing", {})
if (
claim != "reporting.status_changed"
or support is None
or block.get("status_task") != "get_reporting_status"
or not isinstance(signing, dict)
or signing.get("supported") is not True
Comment thread
rachitm022 marked this conversation as resolved.
Resolved
or (handler is not None and support.handler is not handler)
or not ready
):
raise ReportingNotificationError("status_capability_requires_durable_reporting")
if not await support.durable():
raise ReportingNotificationError("status_capability_requires_durable_reporting")
from adcp.server.mcp_tools import get_tools_for_handler

assert support.handler is not None
mounted = {t["name"] for t in get_tools_for_handler(support.handler, _include_schemas=False)}
for field, task in block.items():
if field.endswith("_task") and isinstance(task, str) and task not in mounted:
raise ReportingNotificationError("reporting_capability_requires_mounted_task")


def _project_ready_status_claims(
response: dict[str, Any],
*,
advertised: dict[str, str],
support: ReportingStatusSupport | None,
handler: ADCPHandler[Any],
) -> None:
if advertised:
if advertised != _STATUS_NOTIFICATION_CLAIMS:
raise ReportingNotificationError("status_capability_requires_durable_reporting")
media_buy = response.setdefault("media_buy", {})
if not isinstance(media_buy, dict):
raise ReportingNotificationError("status_capability_requires_durable_reporting")
reporting_delivery = media_buy.setdefault("reporting_delivery", {})
if not isinstance(reporting_delivery, dict) or any(
field in reporting_delivery and reporting_delivery[field] != value
for field, value in advertised.items()
):
raise ReportingNotificationError("status_capability_requires_durable_reporting")
reporting_delivery.update(advertised)
_validate_ready_status_claims(
response,
support=support,
handler=handler,
ready=bool(advertised),
)
Loading
Loading