Skip to content

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

Closed

Description

@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:

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.

Activity

  1. added
    enhancementNew feature or request
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Sep 15, 2026
  2. bokelley commented on Sep 15, 2026

    @bokelley
    ContributorAuthor

    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

  3. added and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Sep 15, 2026
  4. bokelley commented on Sep 16, 2026

    @bokelley
    ContributorAuthor

    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.

  5. bokelley commented on Sep 27, 2026

    @bokelley
    ContributorAuthor

    Audited current main 8ca7dfe0 against the checklist and the rollout decision. Most unchecked boxes describe work already merged.

    #1172 acceptance item Result and implementing PR
    High-level composition of store, producer, handlers, exact reads, notifications, lifecycle Open — draft #1231. #1210/#1218 provide Core orchestration; #1225 provides the full production bridge, but postgres() only constructs the ledger and ordinary adapter registrations still default to memory staging/seals. Simple production adoption still requires hand-assembling the managed/receipt/notification graph. Reuse PgReportingStagingStore, PgReportingSealStore, and the existing production components.
    One registration interface and frozen multi-adapter routing Done — #1210, #1225. ReportingAdapterRegistry and ReportingProductionSourceRegistry; fixed profiles and persisted source context prevent recovery from rerouting a generation.
    Small typed adapter without AdCP transport concerns Done — #1210. ReportingAdapter, frozen slice requests, sync worker-thread and native async fetch.
    Trusted account currency/timezone/route/scope/definition frozen at admission Done — #1210, #1225, with currency/evidence foundations #1175/#1173. Production recovery checks the stored context and live source authorization; D5/R1 revocation/remapping protections remain intact.
    Installed handlers and truthful capabilities Done — #1210, #1192, #1225. Core install plus the mounted production handler provide status, exact reads, consumer status and receipts with actual component/readiness checks.
    Startup validation of impossible combinations Done — #1210, #1225. Service tier/attempt-store checks and production offering/source/verifier/mount checks.
    Deterministic clock, memory stores, failure injection, reusable adapter conformance Open — draft #1232 covers the stronger rollout kit. #1210 already ships DeterministicReportingClock, ScriptedReportingAdapter (sync/async failure queue), and memory staging/seal replay conformance. Public memory destination and notification/attempt stores already exist. #1232 adds named failure points, sync/async barriers, injected durable replay stores, and reusable memory/PG lifecycle assertions while reusing those stores.
    Minimal GAM-like/FreeWheel-like adapters and PostgreSQL production docs Done — #1210, #1225, #1216. Existing examples/reliable_reporting_adapters.py, examples/reporting_service_production.py, examples/reporting_production.py, docs/reliable-reporting-service.md, docs/reporting-source-adapters.md, and the production/upgrade guides cover these; no duplicate examples are needed.
    Advanced component replacement without forking Done — #1210, #1218. Constructor injection, register_executor, storage protocols and the retained low-level APIs preserve advanced composition; production promises require the validated production contracts.
    Related item Result and implementing PR
    #1169 account-scoped generation identity/leases Done, already closed — #1174.
    #1171 frozen per-obligation currency Done, already closed — #1175.
    #1170 constituent/metric evidence Done, already closed — #1173, #1177.
    #1168 transactional notification outbox/activity Done, already closed — #1178, #1183, #1185.
    #1167 Managed Delivery/Reconciled Billing Done, already closed — #1176, #1186, #1187, #1188, #1192, #1215, #1225.

    The rollout's installed JS-buyer/PostgreSQL service interoperability gate remains open in #1199; #1217 is its foundation, not evidence that all four full lifecycle cells passed. Keep #1172 open for the factory, public-kit additions, and that existing interop gate.

    Local audit validation: 214 service/lifecycle/capability, PostgreSQL schedule/admission/lifecycle tests passed. Closed finished sub-issues #1179 and #1180 with their implementing PRs #1192/#1193. Draft #1231 wires durable source storage and the existing managed/receipt/notification graph; its 11 focused memory/PG vectors and 85 affected lifecycle/admission/binding tests pass, along with lint and typecheck-all. db56 reports no blockers on 583efd49. Draft #1232's lint, typecheck-all, and 103 affected tests pass, including 44 new memory/real-PG transaction/autocommit vectors. Full gates and CI remain pending for both; db56 review is requested on #1232. Both await a rebase after #1229's rc.7 adoption.

  6. bokelley commented on Sep 28, 2026

    @bokelley
    ContributorAuthor

    The public lifecycle/failure-point kit gap is now merged as #1232 (ac5e432). PostgreSQL factory/adapter-first composition remains in #1231, currently on rebased head 4756715 with hosted CI green and a clean full local run in progress. #1199 installed-artifact qualification remains separate.

  7. bokelley commented on Sep 28, 2026

    @bokelley
    ContributorAuthor

    Rechecked after #1231 and #1232 merged. The PostgreSQL factory now composes the durable managed pipeline, and the public lifecycle/failure-point kit is merged. The implementation checklist items audited above are covered.

    I am keeping this umbrella open for its explicit rollout close condition: the blocking installed JS-to-Python Core → Managed Delivery → Reconciled Billing lifecycle proof in #1199. The current #1230 four-cell gate passes Core reconciliation against published b16/b18 × rc.47/rc.48 artifacts, but does not yet exercise receipts, signed webhook replay, account activity, or exact revision reads across those four installed cells. I will recheck closure after that full interop gate is delivered.

  8. bokelley commented on Sep 28, 2026

    @bokelley
    ContributorAuthor

    Completed on main at 7549e42. #1231 supplies the adapter-first PostgreSQL factory and managed composition; #1232 supplies the public lifecycle and failure-point conformance kit. The linked lower-level reporting gaps are closed.

    The integrated installed-artifact qualification in #1230 and #1236 passed on this exact main commit: all four Python 8.0.0b16/8.0.0b18 × TypeScript 14.0.0-rc.47/rc.48 Core cells and all four full-lifecycle cells passed with clean isolated state. The full cells exercised Managed Delivery, Reconciled Billing, exact revisions, accepted receipts, and signed webhook retry/replay. No remaining #1172 implementation gap was found. #1199 remains open for its separate release-PR-commit rerun requirement.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions