feat(v3-ref-seller): MediaBuy.invoice_recipient first-class column (3.1 readiness)

[bokelley]

Context

AdCP 3.1 surfaces media_buy.invoice_recipient as a per-buy override of the account's default billing_entity. The v3 reference seller currently captures invoice_recipient only inside the request_snapshot JSON blob — which means it is:

• not queryable
• not enforceable by billing or governance code
• not surfaced in get_media_buy / list_media_buys responses

Refs:

• examples/v3_reference_seller/src/models.py (MediaBuy)
• examples/v3_reference_seller/src/platform.py (create_media_buy, update_media_buy)

Acceptance Criteria

• MediaBuy.invoice_recipient JSON column added to the ORM
• create_media_buy extracts invoice_recipient from the request and persists to the column (still keeping request_snapshot for the full request)
• update_media_buy propagates changes to the column when the buyer updates the field
• get_media_buy / list_media_buys responses populate invoice_recipient from the column
• Smoke test creates a buy with invoice_recipient set, queries it, asserts it round-trips

[bokelley]

Triage

Classification: Feature request
Bucket(s): examples
Status: drafting-pr
Milestone: (omitted — no version target named)

What the experts said:

• dx-expert: non-breaking, well-scoped; _project_invoice_recipient() follows the to_account_response pattern; noted write-only bank trap for agent-buildability
• docs-expert: README spec-versioning section and models.py module docstring both needed updates to reflect 3.1-readiness on MediaBuy; AC5 smoke test clarified as unit (no PG needed)
• code-reviewer (pre-PR): caught str(status_filter) → wrong enum repr returning zero rows; caught generated_poc layering violation; caught NULL currency/total_budget fabrication; caught invoice_recipient not clearable via update

My take: All five acceptance criteria are met. The PR adds the column, wires it through create/update/list, strips write-only bank on the response edge via BusinessEntityResponse, and includes a no-PG smoke test. Three blockers surfaced in pre-PR review were fixed before the PR was opened.

Drafting PR: #395 — MediaBuy.invoice_recipient first-class column + get_media_buys implementation in v3 reference seller.

---

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

---

Generated by Claude Code