feat(reporting): provide an adapter-first ReliableReportingService and conformance kit

[bokelley]

Summary

AdCP 3.2 Reliable Reporting now has strong low-level source, ledger, status, and buyer reconciliation primitives. The adopter experience still requires substantial orchestration: choose account/configuration scope, resolve source routing and currency, construct offerings, wire worker lifecycle, mount handlers, bridge notifications, advertise only installed tiers, and build a conformance harness.

We would like one adapter-first service API where GAM, FreeWheel, and future ad servers provide their domain hooks and the SDK owns the reliable pipeline.

Design target

Adapter authors should implement only the facts their system knows:

• source capabilities and metric semantics;
• fetching one frozen, closed reporting slice;
• currency, source timezone, freshness/finality, and per-metric evidence;
• optionally, managed-destination I/O.

The SDK should own scheduling, leases, retry/replay identity, obligation freezing, staging/sealing, manifests, revisions/adjustments, exact reads, status projections, notifications, receipts, retention, capability advertisement, and lifecycle shutdown.

An illustrative—not prescriptive—shape:

reporting = ReliableReportingService.postgres(
    pool=pool,
    account_context=resolve_account_context,
    webhook_sender=tenant_sender_resolver,
)

reporting.sources.register("gam", GAMReportingAdapter(...))
reporting.sources.register("freewheel", FreeWheelReportingAdapter(...))

platform = reporting.install(platform)

async with reporting:
    await serve(platform)

The per-adapter protocol could center on a single typed fetch_slice() returning normalized rows, watermark, coverage, and per-metric evidence. Routing should use frozen trusted account/media-buy source scope. Sync and async provider SDKs should both be easy to wrap without blocking the event loop.

Acceptance criteria

• One high-level factory/service composes store, producer, status/consumer/receipt handlers, exact revision reads, notification worker, and lifecycle.
• One registration interface routes frozen obligations to multiple source adapters in the same process.
• The minimum adapter protocol is typed, small, and contains no AdCP transport concerns.
• Common account context—currency, timezone, adapter route, source scope, reporting definition—is resolved once from trusted state and frozen at the correct lifecycle boundary.
• Installing the service mounts/returns ready-to-use handlers for the supported AdCP tasks and produces a truthful capability block from actually configured components.
• Startup validation catches impossible combinations (for example reconciled billing without managed delivery, webhook activity without attempt storage, or an offering with no registered source).
• Test utilities provide a deterministic clock, in-memory stores, failure injection, and a reusable adapter conformance suite.
• Documentation includes minimal GAM-like and FreeWheel-like adapters plus PostgreSQL production wiring.
• Advanced adopters can replace individual stores/writers/workers without forking the orchestrator.

Related SDK gaps

This umbrella tracks:

• bug(reporting): scope configuration generations and leases by account #1169 — account-scoped configuration generation identity and leases
• fix(reporting): make currency obligation-scoped for multi-account producers #1171 — per-obligation currency for multi-account producers
• feat(reporting): support per-constituent, per-metric source availability #1170 — per-constituent, per-metric source evidence
• feat(reporting): add a transactional notification outbox and account activity projection #1168 — transactional reporting notification outbox and account activity
• feat(reporting): complete seller-side Managed Delivery and Reconciled Billing #1167 — seller-side Managed Delivery and Reconciled Billing

Why this matters

The client value is not merely schema support. A publisher should be able to enable a demonstrably reliable pipeline, a buyer should be able to query and subscribe to its state, and both parties should get the same exact evidence and billing reconciliation behavior regardless of whether the underlying source is GAM, FreeWheel, or another adapter.

[bokelley]

Triage

Classification: Feature request — umbrella epic
Bucket(s): handlers, client
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: looks-good — adapter surface maps cleanly to existing SDK types (ReportingMetricAvailabilityV1, per-obligation currency); five-child umbrella structure is appropriate because feat(reporting): complete seller-side Managed Delivery and Reconciled Billing #1167–fix(reporting): make currency obligation-scoped for multi-account producers #1171 are load-bearing prerequisites for a truthful ReportingSourceCapabilitiesV1 capability advertisement.
• dx-expert: looks-good — factory/register/install/async context manager is idiomatic Python; minor open question on whether fetch_slice() should return watermark and coverage alongside rows or via a separate adapter.state() call to avoid forcing re-computation on every fetch.
• adtech-product-expert: concern — adapter-first pattern is directionally sound (mirrors Prebid's model) but bundling orchestration lifecycle, startup validation gates, and account context resolution into the same umbrella conflates wire-level reliability primitives with application-framework concerns that may vary too much across publisher stacks to generalize safely.

My take: Protocol and DX reviews validate the architecture; the product concern raises a real scope question about whether ReliableReportingService's startup validation and account context resolution belong in a separate orchestration layer above the five prerequisite issues. Recommend @bokelley confirm the intended scope boundary before implementation begins — treating this issue as the tracking epic with #1167–#1171 as the implementation surface is the lower-risk default.

---

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

---

Generated by Claude Code

[bokelley]

Rollout decisions

This remains the closing umbrella and orchestration/DX layer, built after #1169, #1171, #1170, #1168, and #1167 establish the durable primitives.

• ReliableReportingService composes and validates the existing low-level APIs; it does not replace or deprecate them.
• Trusted account context resolves currency, timezone, adapter route, source scope, and reporting-definition binding once and freezes them on the obligation. Adapter-returned currency is corroborating evidence and fails on mismatch; it is never authoritative.
• Multi-source routing uses a collision-safe (adapter_id, offering_id) identity and freezes the selected route on the obligation.
• Sync provider SDKs are supported through the existing worker-thread pattern; async adapters remain native.
• Capabilities are generated from installed, conformance-proven components and impossible combinations fail at startup.
• The public conformance kit will include a manual clock, scripted sync/async adapters, deterministic failure points, in-memory destination/outbox/attempt components, and reusable memory/PostgreSQL lifecycle assertions.
• A blocking JS-to-Python lane will boot the PostgreSQL-backed Python service over MCP HTTP, invoke reporting tasks through a pinned AdCP 3.2-compatible @adcp/sdk CLI, and run the JS buyer's semantic reconciliation over the same server. A floating/latest lane remains a canary rather than the reproducible floor.

The service issue closes only after the Core -> Managed Delivery -> Reconciled Billing lifecycle, JavaScript buyer interoperability, minimal GAM-like and FreeWheel-like adapters, startup validation, and production wiring documentation are all proven.