feat(reporting): complete seller-side Managed Delivery and Reconciled Billing

[bokelley]

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:

1. resolve a frozen destination configuration for an obligation;
2. materialize the exact canonical revision through a pluggable destination writer;
3. persist immutable delivery attempts/materializations and expose them in status;
4. accept and authenticate sync_reporting_receipts idempotently;
5. enforce receipt replacement, terminal accepted receipts, revision/digest matching, adjustment ordering, and caller visibility;
6. project reconciliation counts/status and capability dependencies (reconciled_billing requires managed_delivery);
7. 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_status returns tier-correct materializations/receipts and reconciliation projection, with strict account/consumer-principal isolation.
• sync_reporting_receipts has 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.

[bokelley]

Triage

Classification: Feature request (epic)
Bucket(s): handlers (get_reporting_status, sync_reporting_receipts) — note: no handlers label exists in this repo; flagging gap
Status: ready-for-human
Milestone: omitted (no version target in issue text)

What the experts said:

• code-reviewer: epic-level scope (4–6 focused PRs minimum); two concrete breaking-change traps in ReportingLedgerStore protocol and ReportingStatusHandler constructor must use additive defaults; credential resolution, receipt-write auth, and content-digest verification surfaces each require human sign-off before merge
• security-reviewer: three independent High/Medium findings on the write path — cross-principal receipt supersession (missing WHERE consumer_id = $caller predicate 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 than IDEMPOTENCY_CONFLICT; new write-side credential path has no existing SDK pattern; financial state machine built from scratch is out of scope for autonomous triage

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

1. Should this issue be converted to an epic with a task list (design doc → store protocols → Pg impl → handler → conformance fixture), or will you sequence it as a series of linked PRs against a single tracking issue?
2. What is the intended source of write-destination credentials for managed delivery — are these stored in Account.reporting_delivery_configs or a new trusted credential store, and should the SDK own freeze/redaction or delegate to the adopter?
3. Should sync_reporting_receipts return an explicit IDEMPOTENCY_CONFLICT error 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]

Implementation split

This epic is being delivered as three reviewable slices after the account-key and obligation-currency foundations:

1. Durable records (active): secret-free frozen destination bindings, immutable materialization attempts, revision receipts, and adjustment receipts in memory and PostgreSQL. This slice adds no higher-tier capability claim and no destination I/O.
2. Verified materialization: pluggable destination writer plus a deterministic reference writer, exact canonical-revision verification, corruption/retry behavior, and transactional readiness integration from feat(reporting): add a transactional notification outbox and account activity projection #1168.
3. Seller surface: ready-to-mount sync_reporting_receipts, tier-correct status/change projections, and dependency-proven Managed/Reconciled capability construction.

Security decisions for the active storage slice:

• account and authenticated consumer principal are part of composite database identity and every write predicate;
• accepted receipts are terminal and rejected replacement is enforced atomically, not read-then-write;
• same idempotency identity with changed financial content is a conflict;
• destination credentials, signed URLs, provider bodies, and arbitrary secret-bearing metadata are never persisted;
• every immutable record participates in the reporting change feed in the same transaction;
• Core deployments keep their current constructor/import behavior and advertise no optional tier until all required components are installed.

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]

Triage (updated — following implementation split comment)

Status: ready-for-human (prior questions resolved; new implementation constraints surfaced)

Three originally flagged concerns — now resolved:

• Cross-principal isolation: ADDRESSED — composite account_id + consumer_id predicate follows record_consumer_status / commit_revision pattern in pg.py
• TOCTOU terminal-receipt race: ADDRESSED — advisory-lock + unique-constraint model mirrors commit_revision at pg.py:381
• Idempotency body mismatch: ADDRESSED — existing IdempotencyStore.wrap already enforces SHA-256 mismatch → IDEMPOTENCY_CONFLICT

New constraints from expert review:

[Ship-blocker / slice 3] consumer_id on the sync_reporting_receipts write path must come from RequestContext.auth_principal, not the receipt body's account field. 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_id is absent. compose_caller_identity (dispatch.py:1052) scopes the idempotency key to the seller account; without the buyer's tenant_id from authenticated transport, all buyers on the same seller share one namespace. Require tenant_id before the handler is admitted.

[Slice 1 pre-PR] Commit to the composite identity field set for MaterializationAttemptRecord and DestinationBindingRecord (anchoring to account_id + authenticated consumer_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 MaterializationAttemptRecord carries ready_at: datetime | None as 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