feat(reporting): add a transactional notification outbox and account activity projection

[bokelley]

Summary

The SDK has generated reporting webhook payloads (ReportingDeliveryReadyWebhook, ReportingStatusChangedWebhook, and ReportingLedgerChangedWebhook) and durable generic webhook sender/supervisor primitives, but ReportingProducer/the reporting ledger has no transactional event or outbox seam connecting committed ledger changes to those publishers.

An adopter that sends after commit can lose a notification on process crash. Sending before commit can publish an event for state that never committed. Reimplementing this bridge in every seller defeats the reliability feature.

The same missing integration prevents honest advertisement of supports_webhook_activity: AdCP expects retained, account-scoped delivery attempts to be returned by list_accounts(include_webhook_activity=true), not merely the ability to make an HTTP request.

Desired SDK behavior

• Persist a reporting notification/outbox record atomically with the ledger transition it describes.
• Map committed transitions to the generated reporting webhook payloads with stable notification IDs and idempotency keys.
• Dispatch through the existing hardened sender/supervisor, including tenant-scoped signing resolution.
• Retain delivery attempts and expose an account-scoped projection/helper suitable for list_accounts webhook activity.
• Supply capability helpers/boot validation so supports_webhook_activity and reporting webhook support are advertised only when the durable components are configured.

An adopter-owned callback may remain as an escape hatch, but the PostgreSQL happy path should not require a second transaction or custom queue implementation.

Acceptance criteria

• Revision, adjustment, issue/status, and materialization transitions enqueue the appropriate notification in the same transaction as the ledger mutation.
• Crash-after-commit and crash-before-commit tests prove no lost or ghost notifications.
• Worker retries preserve the immutable body and idempotency identity while allowing a fresh valid signature.
• Duplicate worker turns and unchanged status do not emit duplicate logical notifications.
• Delivery attempts are retained, account-isolated, paginatable/bounded, and projectable into list_accounts(include_webhook_activity=true).
• Capability construction fails closed or omits activity support when durable event/attempt storage is absent.
• In-memory components exist for tests; PostgreSQL components support multi-worker leasing.
• One end-to-end fixture commits a reporting revision, emits a signed webhook, records a failed/retried/successful attempt, and reads the activity back for only the authorized account.

Adopter impact

This is what lets a buyer-side agent ask “has this publisher sent reporting automatically?” and lets a seller proactively notify/ping the buyer without building an unreliable parallel event system around the SDK ledger.

[bokelley]

Triage

Classification: Feature request (epic)
Bucket(s): handlers, client (no matching repo labels — gap noted)
Status: ready-for-human

What the experts said:

• code-reviewer: Epic-shaped (4–6 PRs); ReportingProducer constructor change is potentially breaking unless outbox is optional with a None-means-no-outbox default; ReportingLedgerStore protocol must expose a connection/transaction handle for true atomic co-commit; notification_id derivation scheme unspecified (content-addressed vs. uuid4-at-enqueue produces very different idempotency guarantees); activity-projection authz model is security-sensitive and needs to be specified against the existing AccountStore contract.
• ad-tech-protocol-expert: Three protocol blockers — (1) supports_webhook_activity appears in multiple capability blocks (ReportingDeliveryCapabilities, account Notifications) and must be disambiguated per scope; (2) ReportingDeliveryReadyWebhook carries x-status: experimental and is Managed-tier only — emitting it for Core adopters is a protocol violation; (3) issue/status transitions must route to ReportingStatusChangedWebhook, not ReportingLedgerChangedWebhook (whose change_kind only has revision_published / adjustment_published).

My take: The acceptance criteria are well-structured but rest on three unresolved architecture decisions that will cascade through the entire implementation. Recommend converting this to an epic with a task list before any PR work starts; the three questions below gate the mapping layer, the constructor contract, and the capability advertising strategy respectively.

@bokelley — three open questions before this can move to implementation:

1. Should ReportingProducer.__init__ gain an optional outbox parameter (defaulting to None = no outbox, preserving existing adopters) or is a required parameter acceptable with an explicit migration note?
2. Which capability block(s) gate supports_webhook_activity for reporting specifically — ReportingDeliveryCapabilities, the account-level Notifications block, or both?
3. Should Core-tier adopters be silently excluded from ReportingDeliveryReadyWebhook dispatch by SDK tier-detection, or does the capability advertisement itself prevent Core configs from reaching the outbox?

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01D4NvcsdtLVAZxPJmRsFfcz

---

Generated by Claude Code

[bokelley]

Rollout decisions

Recording the agreed implementation direction before this enters the durable-state wave:

1. Transaction ownership: the reporting ledger/store transaction owns notification enqueue. We will not make a required ReportingProducer(outbox=...) callback the atomicity boundary. Core remains backwards-compatible with notifications absent; the later service factory configures the durable implementation when installed.
2. Tier filtering: the SDK mapping layer explicitly prevents Core configurations from enqueueing reporting.delivery_ready. Capability advertisement alone is not an internal safety boundary.
3. Webhook mapping: revision/adjustment commits map to reporting.ledger_changed; obligation/configuration health and issue transitions map to reporting.status_changed; verified Managed-tier materializations map to reporting.delivery_ready.
4. Capability truthfulness: media_buy.reporting_delivery.supports_webhook_activity is true only when the reporting attempt/activity projection is durable and installed. account.notifications.supports_webhook_activity is independently true only when list_accounts(include_webhook_activity=true) is actually mounted. Relationship-notification capability is not used as a proxy for reporting activity.
5. Clock transitions: health remains derived, but clock-only transition notifications need a durable notification checkpoint plus a leased sweeper. The checkpoint records what was notified; it does not become the authority for current health.
6. Dependency split: feat(reporting): complete seller-side Managed Delivery and Reconciled Billing #1167 first lands the durable materialization/receipt record contracts without advertising higher tiers. This issue then supplies their transactional notification seam. feat(reporting): complete seller-side Managed Delivery and Reconciled Billing #1167 finishes the handlers, writers, status projections, and capability gates afterward.

Acceptance will include rollback-before-commit, crash-after-commit, receiver-accepted-before-ack, expired lease/multi-worker, immutable body and idempotency identity with fresh signatures, bounded account-isolated activity, and Core-tier exclusion tests over real PostgreSQL.

[bokelley]

Triage (updated)

Classification: Feature request (epic)
Bucket(s): handlers, client
Status: deferred (blocked-on #1167)

Prior open questions — now resolved:

• Q1 (ReportingProducer contract): Transaction ownership moves to the ledger/store; outbox remains optional/absent for Core, configured by the service factory when installed. Backwards-compatible.
• Q2 (capability block scope): media_buy.reporting_delivery.supports_webhook_activity and account.notifications.supports_webhook_activity are independently gated — two separate blocks, not a single proxy.
• Q3 (Core-tier exclusion): The SDK mapping layer explicitly prevents Core configurations from enqueueing reporting.delivery_ready; capability advertisement alone is not the safety boundary.

My take: All three blockers from the prior ready-for-human are resolved. However, rollout-decision 6 establishes a hard prerequisite: #1167 must land its durable materialization/receipt record contracts (without advertising higher tiers) before this issue can supply the transactional notification seam. This is a new child-of-open-parent dependency that gates this work.

Blocked-on: #1167 — resurfaces on merge

---

Triaged by Claude Code. Session: https://claude.ai/code/session_019WcsXUkTrNXmCMSuyQeXZJ

---

Generated by Claude Code