feat(v3-ref-seller): translator pattern with JS mock-server upstream

[bokelley]

Summary

The v3 reference seller stops being an in-process AdCP seller that
duplicates upstream persistence and becomes a translator: AdCP
wire on the inside, the JS mock-server (@adcp/client sales-guaranteed, GAM-flavored) over HTTP on the outside.

The architectural change matters because real adopters — primarily
Prebid's salesagent, GAM-
fronting middleware, FreeWheel-fronting middleware, in-house seller
adapters — already have an ad server. The reference seller should
demonstrate the translator seam, not duplicate the upstream's
persistence inside the AdCP wire layer.

┌──────────────┐        ┌─────────────────────────┐        ┌────────────────┐
│  AdCP buyer  │  MCP/  │  v3 reference seller    │  HTTP  │  JS mock-server │
│   (signed/   │  A2A   │  (this PR)              │  ────► │  (sales-        │
│   bearer)    │ ─────► │                         │        │   guaranteed)   │
└──────────────┘        │  • AdCP wire validation │        └────────────────┘
                        │  • Tier 2 identity gate │              ▲
                        │  • Account translation  │              │
                        │  • Postgres for IDs &   │              │
                        │    commercial relation  │              │
                        └─────────────────────────┘              │
                                  ▲                              │
                                  │                              │
                            ┌─────┴──────┐                       │
                            │ Postgres   │                       │
                            │ (tenants,  │                       │
                            │  agents,   │                       │
                            │  accounts) │                       │
                            └────────────┘                       │
                                                                 │
                              network_code + advertiser_id ──────┘

The local Postgres carries only the commercial-identity layer. Ad-ops
state — orders / line items / creatives / delivery — lives upstream.
Each Account.ext carries {network_code, advertiser_id} so the
translator can route requests to the right upstream tenant.

Key changes

• New src/upstream.py — httpx-based MockUpstreamClient
  mirroring the JS mock's openapi.yaml 1:1 (products, inventory,
  forecast, availability, orders, lineitems, creatives, delivery,
  conversions/CAPI, tasks).
• Models drop MediaBuy / Creative / PerformanceFeedback —
  ad-ops state lives upstream. Account.ext carries the translation
  routing.
• Platform rewires every ad-ops method to call the upstream over
  HTTP. create_media_buy returns a TaskHandoff for the upstream's
  pending_approval path; the framework surfaces a Submitted
  envelope to the buyer and a background coroutine polls
  /v1/tasks/{id} until the upstream auto-approves.
  update_media_buy raises UNSUPPORTED_FEATURE (the mock has no
  order-update endpoint; real adopters wire their PATCH flow).
  sync_accounts / list_accounts stay local Postgres — that mapping
  is the durable record this seller owns.
• Capabilities claim BOTH sales-non-guaranteed AND
  sales-guaranteed — the mock supports both delivery_types, and
  real GAM-shaped publishers sell both surfaces.
• Tests use respx to mock httpx so the Python pytest CI run
  doesn't need to boot Node. New CI jobs:
  v3-reference-seller-tests (pytest, no JS) and
  storyboard-v3-reference-seller (boots the JS mock + Python seller
  for the real storyboard runner).
• New MIGRATION.md for maintainers of pre-v3 sales agents
  (Prebid's salesagent as the primary use case): fork this directory,
  replace MockUpstreamClient with your real ad-server client,
  reseed Account.ext, deploy.

Migration use case (Prebid salesagent)

The translator pattern is what an existing Prebid salesagent operator
needs. They already have an ad-ops integration (orders / line items /
delivery against their backing system); they need the AdCP wire layer
and the Tier 2 commercial-identity gate without rewriting their
ad-ops code. The new MIGRATION.md walks them through:

1. Fork examples/v3_reference_seller as their starting point.
2. Replace MockUpstreamClient with their existing upstream client.
3. Reseed BuyerAgent / Account tables with their tenant config.
4. Deploy.

Their existing upstream code is preserved verbatim. Only the AdCP
wire layer comes from the SDK.

Test plan

• pytest examples/v3_reference_seller/tests/ -v — 23 tests pass
  (Protocol surface, projection guards, every translator method
  asserts the right upstream HTTP call via respx).
• ruff check src/ examples/v3_reference_seller/ — clean.
• mypy src/adcp/ — 747 source files, no issues.
• pytest tests/ — full main test suite still passes
  (3204 passed).
• CI: v3-reference-seller-tests runs the respx-mocked tests.
• CI: storyboard-v3-reference-seller boots the real JS mock-
  server + Python seller and runs the canonical storyboard runner
  (non-blocking initially per the existing storyboard job pattern).

🤖 Generated with Claude Code