Repository navigation
Description
Summary
The beta.15 seller reporting stack implements Core reporting only. ReportingStatusHandler explicitly returns empty materializations and receipts, and obligation projection hardcodes reconciliation_mode="delivery_only". Buyer-side reconciliation and sync_reporting_receipts client primitives exist, but there is no corresponding SDK-owned seller path for Managed Delivery or Reconciled Billing.
That makes the optional capabilities present in the generated AdCP 3.2 schemas much harder to implement safely and prevents sellers from honestly advertising those tiers.
Requested seller-side vertical slice
Build the durable seller primitives that extend Core without weakening it:
- resolve a frozen destination configuration for an obligation;
- materialize the exact canonical revision through a pluggable destination writer;
- persist immutable delivery attempts/materializations and expose them in status;
- accept and authenticate
sync_reporting_receiptsidempotently; - enforce receipt replacement, terminal accepted receipts, revision/digest matching, adjustment ordering, and caller visibility;
- project reconciliation counts/status and capability dependencies (
reconciled_billingrequiresmanaged_delivery); - emit transactional reporting delivery/ledger notifications through the reporting outbox.
Object-store/warehouse implementations can be separate adapters. The core SDK should define the contracts, persistence, state machine, and at least one reference destination implementation.
Acceptance criteria
- Seller-side store/service protocols and PostgreSQL implementations persist immutable materializations, revision receipts, and adjustment receipts.
-
get_reporting_statusreturns tier-correct materializations/receipts and reconciliation projection, with strict account/consumer-principal isolation. -
sync_reporting_receiptshas a ready-to-mount seller handler with authentication, idempotency, immutable acceptance/replacement, and typed errors. - Destination credentials/configuration are resolved from trusted account state, frozen appropriately, and never leaked in status or logs.
- Materializations are verified against the exact revision canonical content digest, row count, control totals, and declared format before becoming available/delivered.
- Adjustments and their receipts preserve official-revision/finality rules.
- Capability helpers enforce tier dependencies and refuse to advertise incomplete implementations.
- A lifecycle/conformance fixture covers Core -> Managed Delivery -> Reconciled Billing, including corruption, retry, rejected receipt replacement, accepted terminal receipt, and adjustment reconciliation.
- Existing Core-only deployments remain supported without destination or receipt dependencies.
Adopter impact
Embedded Sales Agent wants GAM, FreeWheel, and other source adapters to plug into one reliable pipeline while the SDK owns protocol state. We should not have to recreate the financial reconciliation state machine in every seller implementation.
Activity
bokelley commentedon Sep 15, 2026
Triage
Classification: Feature request (epic)
Bucket(s): handlers (
get_reporting_status,sync_reporting_receipts) — note: nohandlerslabel exists in this repo; flagging gapStatus: ready-for-human
Milestone: omitted (no version target in issue text)
What the experts said:
ReportingLedgerStoreprotocol andReportingStatusHandlerconstructor must use additive defaults; credential resolution, receipt-write auth, and content-digest verification surfaces each require human sign-off before mergeWHERE consumer_id = $callerpredicate at write time), TOCTOU race on terminal accepted state (must be an atomic DB predicate, not a read-then-write), and idempotency key replay with financial body mismatch returning silent cache hit rather thanIDEMPOTENCY_CONFLICT; new write-side credential path has no existing SDK pattern; financial state machine built from scratch is out of scope for autonomous triageMy take: This is an epic with at least three security-bearing surfaces (destination credential isolation, atomic terminal-receipt enforcement, consumer-principal write isolation) that require an architectural design doc before any PR lands. Flagging for @bokelley to scope and sequence, and to confirm whether a design doc or an ADR is the preferred artifact before work starts.
Open questions for @bokelley:
Account.reporting_delivery_configsor a new trusted credential store, and should the SDK own freeze/redaction or delegate to the adopter?sync_reporting_receiptsreturn an explicitIDEMPOTENCY_CONFLICTerror when the same idempotency key is replayed with a mismatched receipt body, or is silent replay (current behavior of_idempotency.py) acceptable for billing-tier receipts?Triaged by Claude Code. Session: https://claude.ai/code/session_01Dcd68YX9mnicByjbKKg2in
Generated by Claude Code
bokelley commentedon Sep 16, 2026
Implementation split
This epic is being delivered as three reviewable slices after the account-key and obligation-currency foundations:
sync_reporting_receipts, tier-correct status/change projections, and dependency-proven Managed/Reconciled capability construction.Security decisions for the active storage slice:
Shared memory/PostgreSQL vectors and real PostgreSQL concurrency tests cover first-leaf races, rejected replacement races, cross-principal/account attempts, terminal materialization races, exact digest/evidence matching, adjustment ordering, migrations, restart, and checkpoint isolation. #1168’s outbox slices follow the durable-record slice before the final materializer/handler work, so notification enqueue can be integrated transactionally.
bokelley commentedon Sep 16, 2026
Triage (updated — following implementation split comment)
Status: ready-for-human (prior questions resolved; new implementation constraints surfaced)
Three originally flagged concerns — now resolved:
account_id+consumer_idpredicate followsrecord_consumer_status/commit_revisionpattern inpg.pycommit_revisionatpg.py:381IdempotencyStore.wrapalready enforces SHA-256 mismatch →IDEMPOTENCY_CONFLICTNew constraints from expert review:
[Ship-blocker / slice 3]
consumer_idon thesync_reporting_receiptswrite path must come fromRequestContext.auth_principal, not the receipt body'saccountfield. Accepting it from the body re-opens cross-principal supersession regardless of the DB predicate. This needs to be an explicit implementation constraint.[Medium / slice 3] Idempotency scope can collapse when
tenant_idis absent.compose_caller_identity(dispatch.py:1052) scopes the idempotency key to the seller account; without the buyer'stenant_idfrom authenticated transport, all buyers on the same seller share one namespace. Requiretenant_idbefore the handler is admitted.[Slice 1 pre-PR] Commit to the composite identity field set for
MaterializationAttemptRecordandDestinationBindingRecord(anchoring toaccount_id+ authenticatedconsumer_id) before the PR opens — DDL and in-memory dedup key depend on it.[Slice 1 pre-PR] "Destination credentials never persisted" needs enforcement in the store layer (a typed field constraint on the frozen binding), not just by convention.
[Slice 1/2 coordination] Confirm whether
MaterializationAttemptRecordcarriesready_at: datetime | Noneas a placeholder for #1168, or arrives as additive in slice 2.Triaged by Claude Code. Session: https://claude.ai/code/session_01GTt4FMz3G7VMuRfHfVRkTY
Generated by Claude Code
test(reporting): close receipt foreign-target and adjustment-chain co…
test(reporting): exercise the account tuple column at the receipt wri…
fix(reporting): give period-close leasing a durable total fairness order
fix(reporting): give period-close leasing a durable total fairness order