You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
feat(reporting): add a transactional notification outbox and account activity projection #1168
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.
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:
Should ReportingProducer.__init__ gain an optionaloutbox parameter (defaulting to None = no outbox, preserving existing adopters) or is a required parameter acceptable with an explicit migration note?
Which capability block(s) gate supports_webhook_activity for reporting specifically — ReportingDeliveryCapabilities, the account-level Notifications block, or both?
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?
Recording the agreed implementation direction before this enters the durable-state wave:
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.
Tier filtering: the SDK mapping layer explicitly prevents Core configurations from enqueueing reporting.delivery_ready. Capability advertisement alone is not an internal safety boundary.
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.
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.
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.
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.
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.
Activity
bokelley commentedon Sep 15, 2026
Triage
Classification: Feature request (epic)
Bucket(s): handlers, client (no matching repo labels — gap noted)
Status: ready-for-human
What the experts said:
ReportingProducerconstructor change is potentially breaking unless outbox is optional with aNone-means-no-outbox default;ReportingLedgerStoreprotocol must expose a connection/transaction handle for true atomic co-commit;notification_idderivation 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 existingAccountStorecontract.supports_webhook_activityappears in multiple capability blocks (ReportingDeliveryCapabilities, account Notifications) and must be disambiguated per scope; (2)ReportingDeliveryReadyWebhookcarriesx-status: experimentaland is Managed-tier only — emitting it for Core adopters is a protocol violation; (3) issue/status transitions must route toReportingStatusChangedWebhook, notReportingLedgerChangedWebhook(whosechange_kindonly hasrevision_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:
ReportingProducer.__init__gain an optionaloutboxparameter (defaulting toNone= no outbox, preserving existing adopters) or is a required parameter acceptable with an explicit migration note?supports_webhook_activityfor reporting specifically —ReportingDeliveryCapabilities, the account-level Notifications block, or both?ReportingDeliveryReadyWebhookdispatch 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 commentedon Sep 16, 2026
Rollout decisions
Recording the agreed implementation direction before this enters the durable-state wave:
ReportingProducer(outbox=...)callback the atomicity boundary. Core remains backwards-compatible with notifications absent; the later service factory configures the durable implementation when installed.reporting.delivery_ready. Capability advertisement alone is not an internal safety boundary.reporting.ledger_changed; obligation/configuration health and issue transitions map toreporting.status_changed; verified Managed-tier materializations map toreporting.delivery_ready.media_buy.reporting_delivery.supports_webhook_activityis true only when the reporting attempt/activity projection is durable and installed.account.notifications.supports_webhook_activityis independently true only whenlist_accounts(include_webhook_activity=true)is actually mounted. Relationship-notification capability is not used as a proxy for reporting activity.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 commentedon Sep 16, 2026
Triage (updated)
Classification: Feature request (epic)
Bucket(s): handlers, client
Status: deferred (blocked-on #1167)
Prior open questions — now resolved:
outboxremains optional/absent for Core, configured by the service factory when installed. Backwards-compatible.media_buy.reporting_delivery.supports_webhook_activityandaccount.notifications.supports_webhook_activityare independently gated — two separate blocks, not a single proxy.reporting.delivery_ready; capability advertisement alone is not the safety boundary.My take: All three blockers from the prior
ready-for-humanare 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
fix(reporting): apply rc.3 configuration lifecycle and keep issue ret…
feat(reporting): expose durable webhook activity
feat(reporting): expose durable webhook activity
fix(reporting): roll back rejected default-off issue scope moves
fix(reporting): pin the A/B rolling gate to a C-collated database
fix(reporting): pin every frozen-artifact CI job to a C-collated cluster
ci(reporting): widen the Postgres conformance job budget to 30 minutes