Skip to content

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

Closed

Description

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

Activity

  1. added
    bugSomething isn't working
    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: 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

  3. added and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Sep 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions