Repository navigation
Description
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.
Activity
bokelley commentedon Sep 15, 2026
Triage
Classification: Feature request — umbrella epic
Bucket(s): handlers, client
Status: ready-for-human
What the experts said:
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 truthfulReportingSourceCapabilitiesV1capability advertisement.fetch_slice()should return watermark and coverage alongside rows or via a separateadapter.state()call to avoid forcing re-computation on every fetch.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 commentedon Sep 16, 2026
Rollout decisions
This remains the closing umbrella and orchestration/DX layer, built after #1169, #1171, #1170, #1168, and #1167 establish the durable primitives.
ReliableReportingServicecomposes and validates the existing low-level APIs; it does not replace or deprecate them.(adapter_id, offering_id)identity and freezes the selected route on the obligation.@adcp/sdkCLI, 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.
bokelley commentedon Sep 27, 2026
Audited current main
8ca7dfe0against the checklist and the rollout decision. Most unchecked boxes describe work already merged.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. ReusePgReportingStagingStore,PgReportingSealStore, and the existing production components.ReportingAdapterRegistryandReportingProductionSourceRegistry; fixed profiles and persisted source context prevent recovery from rerouting a generation.ReportingAdapter, frozen slice requests, sync worker-thread and native async fetch.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.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.register_executor, storage protocols and the retained low-level APIs preserve advanced composition; production promises require the validated production contracts.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.bokelley commentedon Sep 28, 2026
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.
bokelley commentedon Sep 28, 2026
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.
bokelley commentedon Sep 28, 2026
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.