fix(reporting): make currency obligation-scoped for multi-account producers

[bokelley]

Summary

Reliable Reporting currently takes one process-wide ProducerOfferings.currency (default "USD") and copies it into every ReportingSourceSliceRequestV1. A multi-account producer cannot truthfully run accounts, media buys, or immutable report definitions in different currencies through one producer.

Currency is part of reporting correctness: the source contract validates it, monetary control-total units must agree with the pinned report definition, and consumers have a specific currency_mismatch status. It therefore must be resolved and frozen at the same durable scope as the obligation/revision, not supplied as mutable process configuration.

Desired SDK contract

Provide an SDK-owned resolution seam and durable representation. For example:

CurrencyResolver = Callable[
    [ReportingConfiguration, ReportingObligationRecord],
    Awaitable[str] | str,
]

ReportingProducer(..., currency_resolver=...)

The exact API can instead derive currency from an immutable report-definition binding. The important invariants are:

1. resolve from trusted account/configuration/report-definition state;
2. freeze the ISO 4217 code before source work starts;
3. persist enough information that retries, restatements, status checks, and audits cannot change currency later;
4. reject or deterministically partition mixed-currency scopes rather than aggregating incompatible money.

The existing fixed currency= option can remain as a convenient single-currency resolver/default, but it should not be the only supported shape.

Acceptance criteria

• One producer can concurrently publish an EUR account and a USD account without separate processes or mutable global state.
• Currency is derived from trusted, immutable configuration/definition/account data—not buyer context or a transient adapter response.
• The resolved currency is frozen durably before acquisition and is stable across retry, restart, correction, and official restatement.
• The SDK validates three-letter uppercase currency codes and ensures monetary rows/control totals agree with the pinned definition.
• Mixed-currency obligations fail explicitly or are partitioned before aggregation; they are never silently coerced to USD.
• Source request/manifest conformance and consumer currency_mismatch checks remain end-to-end testable.
• Fixtures and documentation include a non-USD, multi-account example.

Adopter impact

Embedded Sales Agent supports tenant/account currencies and GAM-backed buys. Hardcoding USD would produce incorrect evidence and potentially incorrect billing reconciliation for non-USD clients, so it blocks a trustworthy rollout.

[bokelley]

Triage

Classification: Bug (reporting correctness — multi-currency producers publish wrong currency on every slice)
Bucket(s): client (reporting/ledger producer)
Status: ready-to-implement
Milestone: omitted (no version label or milestone on issue)

What the experts said:

• code-reviewer: Resolve currency at obligation-commit time (_close_elapsed_periods), not at slice-build time — TOCTOU-unsafe otherwise; persist on ReportingObligationRecord with currency: str | None = None (non-breaking at Python level); CurrencyResolver must handle sync/async dual-dispatch or force async to avoid the coroutine foot-gun.
• ad-tech-protocol-expert: publication_content_fingerprint_v1 includes currency (source.py:1653), so a currency change between a first attempt and a retry produces a replay violation; _semantic_scope in conformance.py (line 567) also includes currency, meaning a mid-sequence currency change causes unrecoverable REVISION_SEQUENCE_INVALID; mixed-currency within one obligation is a rejection problem (fail at commit time), not a partition problem — cross-account diversity is handled by separate obligations each carrying their own frozen currency.

My take: Both experts agree the fix is correct and the invariant is already partially enforced at the protocol layer — what's missing is the obligation-time freeze. Adding an optional currency_resolver to ProducerOfferings with a fallback to the existing currency: str = "USD" field is a non-breaking additive change at the Python level; the pg store layer needs a DEFAULT NULL column addition for ReportingObligationRecord.currency but no data migration.

Implementation brief:

• ProducerOfferings (ledger/producer.py:114): Add currency_resolver: Callable[[ReportingConfiguration, ReportingObligationRecord], Awaitable[str] | str] | None = None; when None, fall back to the existing currency field. Force callers to use async def resolvers or add inspect.isawaitable() conditional-await to support both shapes. The existing currency: str = "USD" field stays as the default single-currency resolver.
• ReportingObligationRecord (ledger/models.py): Add currency: Annotated[str, StringConstraints(pattern=r"^[A-Z]{3}$")] | None = None (after created_at; optional so existing persisted records deserialize cleanly). Resolve and set it inside _close_elapsed_periods() before calling commit_obligation().
• _build_slice() (ledger/producer.py:628): Read obligation.currency (with fallback to self._offerings.currency if None) rather than self._offerings.currency directly at line 720. Add an assertion that the resolved value matches ^[A-Z]{3}$ before building the frozen request.
• Tests and fixtures: Add a multi-account fixture with EUR + USD obligations to src/adcp/reporting/fixtures.py (currently hardcoded "USD" at line 260); extend tests/reporting/ with a test asserting that two concurrent obligations for the same producer carry independently resolved currencies, and that a retry uses the obligation's frozen currency rather than re-resolving. The pg backend (ledger/pg.py) needs a DEFAULT NULL column addition and a deserialization path for rows without the column.

---

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

---

Generated by Claude Code