feat(examples): v3 reference seller — runnable Tier 2 + v3 wiring (#357) (#373)

* feat(examples): v3 reference seller — runnable Tier 2 + v3 wiring (#357)

Multi-file directory under ``examples/v3_reference_seller/`` that
wires every Tier 2 / v3-supporting component into one runnable
adopter pattern. Spec 3.0-compliant on the wire, 3.1-ready in
architecture and storage.

* ``src/models.py`` — SQLAlchemy 2.0 models (Tenant, BuyerAgent,
  Account, MediaBuy) with 3.1-ready columns.
* ``src/tenant_router.py`` — SQL-backed SubdomainTenantRouter with
  in-process cache.
* ``src/buyer_registry.py`` — tenant-scoped BuyerAgentRegistry.
* ``src/audit.py`` — DbAuditSink writing audit_events.
* ``src/platform.py`` — sales-non-guaranteed impl (the bulk of
  what an adopter customizes).
* ``src/app.py`` — main entrypoint wiring serve(transport="both")
  + a ``build_app`` helper composing SubdomainTenantMiddleware on
  the parent Starlette app.
* ``seed.py`` + ``docker-compose.yml`` — dev fixtures + Postgres.
* ``README.md`` — clone-and-modify guide.
* ``tests/test_smoke.py`` — 7 import + Protocol-conformance tests.

End-to-end verified locally against postgres:16. The compose uses
``POSTGRES_HOST_AUTH_METHOD=trust`` for loopback dev — no literal
password in version control; production sellers source DB
credentials from a secrets backend.

Closes #357 (MVP). Follow-ups: HTTP-Sig verifier middleware in
context_factory, admin CRUD API, Alembic migrations, swap to
PgTaskRegistry / PgWebhookDeliverySupervisor for production.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(v3-reference-seller): expert-review fix-pack + serve(asgi_middleware=)

The 4-expert review of #357 surfaced multiple convergent blockers
in the v3 reference seller MVP:

* `app.py` `build_app()` imported `_build_mcp_and_a2a_app` from the
  wrong module → ImportError at adopter call time
* `main()` never wired `SubdomainTenantMiddleware` → multi-tenant
  claim was false; `current_tenant()` would return None
* `platform.create_media_buy` extracted `total_budget` / `currency` /
  `start_time` / `end_time` against a wrong-shape API surface
  (TotalBudget object, StartTiming union) — every persisted media
  buy stored corrupted data or NULL
* `media_buy_id = f"mb_{uuid[:16]}"` collides at scale → IntegrityError

Bundled fix:

* Framework: add `asgi_middleware=Sequence[(cls, kwargs)]` kwarg to
  `adcp.server.serve()` (and forward through
  `adcp.decisioning.serve()`) so adopters layer Starlette-style
  ASGI middleware without dropping to `_build_mcp_and_a2a_app`.
* Example: `main()` now passes `asgi_middleware=[(SubdomainTenant
  Middleware, {"router": router})]`. Dead `build_app()` helper
  removed.
* `platform.py`: project `req.total_budget.amount/.currency` and
  unwrap `StartTiming.root` (`'asap'` → now()); `media_buy_id` is a
  full UUID (the (tenant_id, idempotency_key) unique constraint
  already guards replay).
* `models.py` + `buyer_registry.py` + `seed.py`: `billing_capabilities`,
  `default_terms`, `allowed_brands` switched from JSON-encoded
  String columns to native JSON columns (matches the rest of the
  schema).
* `audit.py`: docstring corrected — `record()` is best-effort but
  awaited inline (not fire-and-forget).
* `tenant_router.py`: cache renamed from "LRU-ish" to bounded FIFO
  to match actual eviction behavior.
* `README.md`: drop inaccurate claims (HTTP-Sig wired,
  project_account_for_response wired inline). Add dev-only callout
  for docker-compose trust auth + seed bearer token.

Test: `tests/test_serve_asgi_middleware.py` covers the new kwarg's
no-op + outermost-first composition contract.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(v3-reference-seller): pricing_options conformance + docstring polish

Protocol-expert review surfaced one BLOCKER on commit 8d6d783:
``pricing_options`` in the get_products stub didn't conform to the
spec's ``CpmPricingOption`` shape — used ``type``/``rate`` keys
instead of the discriminator ``pricing_model`` and required
``fixed_price``, and was missing the required
``pricing_option_id``. Buyer agents validating the response
against the discriminated union would reject the seller's catalog.

Also addresses two should-fix items:

* ``serve(asgi_middleware=)`` docstring now warns adopter middleware
  to pass through ``lifespan`` and ``websocket`` scopes so the
  framework's lifespan composition still runs.
* README "Alembic migrations" callout clarifies that
  ``create_all`` does NOT detect column renames or type changes
  on existing tables — adopters who prototyped against earlier
  branches need to drop/recreate the dev database after pulling
  the JSON-column rename.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bokelley

examples/v3_reference_seller/README.md

@@ -0,0 +1,185 @@
+# v3 reference seller
+
+Canonical multi-tenant AdCP seller. **Spec 3.0-compliant on the wire,
+3.1-ready in architecture and storage.** Adopters fork this directory
+and replace the platform impl with their own business logic.
+
+This directory wires every Tier 2 / v3-supporting component the SDK
+ships into one runnable binary:
+
+| Component | Module | Source |
+|---|---|---|
+| Tier 2 commercial-identity gate | `src/buyer_registry.py` | `adcp.decisioning.BuyerAgentRegistry` |
+| Subdomain tenant routing | `src/tenant_router.py` + `src/app.py` | `adcp.server.SubdomainTenantMiddleware` |
+| Account v3 storage (bank-details column) | `src/models.py` | `Account.billing_entity` JSON column |
+| Audit trail | `src/audit.py` | `adcp.audit_sink.AuditSink` |
+| MCP + A2A on one binary | `src/app.py` | `serve(transport="both", asgi_middleware=...)` |
+| Durable HITL tasks (optional) | swap to `PgTaskRegistry` | `adcp.decisioning.pg.PgTaskRegistry` |
+| Durable webhook delivery (optional) | swap to `PgWebhookDeliverySupervisor` | `adcp.webhook_supervisor_pg` |
+| HTTP-Sig verifier → AuthInfo (TODO) | adopter middleware | `adcp.decisioning.AuthInfo.from_verified_signer` |
+| Account v3 projection on read (TODO) | adopter wires in `sync_accounts` | `adcp.types.project_account_for_response` |
+
+## Run it
+
+```bash
+# 1. Start Postgres
+cd examples/v3_reference_seller
+docker compose up -d postgres
+
+# 2. Seed dev fixtures
+DATABASE_URL=postgresql+asyncpg://postgres@localhost/adcp \
+  python -m seed
+
+# 3. Boot the seller
+DATABASE_URL=postgresql+asyncpg://postgres@localhost/adcp \
+  python -m src.app
+```
+
+The server binds `0.0.0.0:3001` and serves both transports.
+
+> ⚠️ **Local-dev only.** `docker-compose.yml` uses
+> `POSTGRES_HOST_AUTH_METHOD=trust` and exposes 5432 on
+> `0.0.0.0`. Do not run this compose file on a host reachable from
+> an untrusted network. `seed.py` plants a literal dev bearer
+> token (`dev-bearer-token-acme-1`) — do not run `seed.py` against
+> a production `DATABASE_URL`. Production deployments point
+> `DATABASE_URL` at managed Postgres with scram-sha-256 + a real
+> password, and seed via the admin API (not this script).
+
+## What's wired
+
+### Schema (`src/models.py`)
+
+Four tables — the spine of a multi-tenant v3 seller:
+
+- `tenants` — one row per `<subdomain>.example.com`.
+  `SubdomainTenantMiddleware` reads the request `Host` header and
+  finds the matching row.
+- `buyer_agents` — Tier 2 commercial-identity rows. The framework's
+  dispatch gate reads this BEFORE the platform method runs and
+  rejects suspended (transient) and blocked (terminal) agents with
+  structured errors.
+- `accounts` — buyer-side accounts under recognized agents. Carries
+  the spec 3.1-ready `billing_entity` (write-only bank details on
+  responses) and `reporting_bucket` (offline reporting target). The
+  reference seller does not implement `sync_accounts`, so the
+  bank-details projection is a column-level architectural seam, not
+  an enforced runtime guard — adopters who add `sync_accounts`
+  MUST project through `adcp.types.project_account_for_response`
+  before returning the row.
+- `media_buys` — terminal artifact of `create_media_buy`,
+  idempotency-keyed for replay safety.
+
+### Tenant routing (`src/tenant_router.py`)
+
+`SqlSubdomainTenantRouter` implements the framework's
+`SubdomainTenantRouter` Protocol. The middleware sets the
+`current_tenant()` contextvar; downstream stores
+(`buyer_registry.py`, `platform.py`) read it without explicit
+plumbing.
+
+### Commercial-identity gate (`src/buyer_registry.py`)
+
+`TenantScopedBuyerAgentRegistry` extends the framework's
+`PgBuyerAgentRegistry` pattern with tenant scoping — the same
+`agent_url` can have different commercial postures across tenants.
+Implements both `resolve_by_agent_url` (signed traffic) and
+`resolve_by_credential` (bearer / OAuth).
+
+### Audit trail (`src/audit.py`)
+
+`DbAuditSink` writes one `audit_events` row per skill dispatch.
+Failures are swallowed by the framework's audit middleware (the
+sink is fire-and-forget by Protocol contract). Adopters with Slack
+alerting compose with `adcp.audit_sink.SlackAlertSink` via
+`CompositeAuditSink`.
+
+### Platform (`src/platform.py`)
+
+`V3ReferenceSeller` implements `sales-non-guaranteed` — the five
+required Sales methods (`get_products`, `create_media_buy`,
+`update_media_buy`, `sync_creatives`, `get_media_buy_delivery`).
+Every method body reads `ctx.buyer_agent` (the resolved Tier 2
+record) and `ctx.account` (the resolved account); both are
+populated by the framework's dispatch gate before the method runs.
+
+This file is the bulk of what an adopter customizes. Everything
+else is boilerplate the seller wires once.
+
+## Auth modes
+
+The seller supports both v3 signed-request and pre-trust beta
+bearer auth simultaneously — the `BuyerAgentRegistry` dispatches
+on credential kind. Adopter middleware constructs `AuthInfo` two
+ways:
+
+```python
+# Signed (v3) — produces typed HttpSigCredential
+auth = AuthInfo.from_verified_signer(
+    signer,                       # from adcp.signing.verify_request_signature
+    max_verified_age_s=300.0,     # reject stale signers
+)
+
+# Bearer (pre-trust beta) — typed ApiKeyCredential
+auth = AuthInfo(
+    kind="bearer",
+    credential=ApiKeyCredential(kind="api_key", key_id=token_id),
+)
+```
+
+Both put the typed credential into `ctx.metadata['adcp.auth_info']`
+where the framework picks it up.
+
+## What's NOT wired (yet)
+
+These ship as separable follow-ups — the framework's components
+exist; the reference seller wires the simpler defaults:
+
+- **HTTP-Sig verifier middleware** — adopters add
+  `verify_request_signature` in their `context_factory` once
+  AAO publishes the brand.json registry. The Tier 1 SDK primitives
+  ship in `adcp.signing`; this seller uses bearer auth in the seed.
+- **Brand authorization (Tier 3)** — gated on ADCP spec issue
+  #3690.
+- **Postgres `TaskRegistry` / `WebhookDeliverySupervisor`** —
+  swap `InMemoryTaskRegistry` → `PgTaskRegistry` and
+  `InMemoryWebhookDeliverySupervisor` → `PgWebhookDeliverySupervisor`
+  in `src/app.py` for production durability. Both classes ship in
+  the SDK; this seller's `app.py` uses the in-memory variants for
+  fast iteration.
+- **Alembic migrations** — `Base.metadata.create_all` runs at boot
+  (idempotent on table existence — it does NOT detect column
+  renames or type changes on existing tables). Adopters who
+  prototyped against earlier branches and pulled new column
+  changes should drop and recreate the dev database; production
+  sellers wire Alembic and version their schema changes.
+- **Admin CRUD API** — separate Starlette app for tenant / agent
+  CRUD. Patterns to come; for now use `seed.py` and direct SQL.
+
+## Customization
+
+Adopters typically change:
+
+1. **`src/platform.py`** — the platform method bodies. Replace the
+   stub product catalog, add your CMS query for `get_products`,
+   route `create_media_buy` into your real DSP / ad-server, etc.
+2. **`src/audit.py`** — extend `details` with adopter-specific
+   fields (decision flags, fraud scores, A/B variant ids).
+3. **Auth wiring in `src/app.py`** — wire your verifier middleware
+   that constructs `AuthInfo`.
+
+Adopters typically *don't* change:
+
+- Models — the v3 schema is the contract.
+- Tenant router logic — the Protocol shape is fixed.
+- Audit middleware composition — the framework wires it.
+- The unified MCP+A2A binary — `transport="both"` is one knob.
+
+## Spec versioning
+
+This seller is **3.0-compliant on the wire** — every field it sends
+matches the AdCP 3.0 schemas. The schema and architecture is
+**3.1-ready** (`billing_entity` + `reporting_bucket` columns,
+typed `BillingMode`, write-only bank-details projection). Sellers
+running this code today serve 3.0 buyers; the same code serves
+3.1 buyers when the spec lands.

examples/v3_reference_seller/docker-compose.yml

@@ -0,0 +1,28 @@
+# Dev-only Postgres for the v3 reference seller. Production sellers
+# point ``DATABASE_URL`` at their managed Postgres (RDS, Cloud SQL,
+# Neon, Supabase) and skip this file entirely.
+
+services:
+  postgres:
+    image: postgres:16
+    environment:
+      POSTGRES_DB: adcp
+      # ``trust`` is fine for the loopback dev compose; production
+      # deployments use scram-sha-256 + a real password sourced from
+      # a secrets backend (Vault, AWS Secrets Manager, sealed-secrets).
+      # No POSTGRES_PASSWORD here on purpose — the ``trust`` auth
+      # method makes it unused, and shipping a literal in version
+      # control flags secret-scanners.
+      POSTGRES_HOST_AUTH_METHOD: trust
+    ports:
+      - "5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d adcp"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+    volumes:
+      - pg_data:/var/lib/postgresql/data
+
+volumes:
+  pg_data:

examples/v3_reference_seller/seed.py

@@ -0,0 +1,109 @@
+"""Dev fixtures — seed two tenants + buyer agents for local
+end-to-end testing.
+
+::
+
+    docker compose up -d postgres
+    DATABASE_URL=postgresql+asyncpg://postgres@localhost/adcp \\
+      python -m examples.v3_reference_seller.seed
+
+After seeding, hit:
+
+* ``http://acme.localhost:3001/.well-known/agent.json``  (A2A)
+* ``http://acme.localhost:3001/mcp``                     (MCP)
+
+with a buyer agent's signed-request or bearer credential matching
+the seeded ``api_key_id``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from src.models import Account, Base, BuyerAgent, Tenant
+
+
+async def main() -> None:
+    db_url = os.environ.get(
+        "DATABASE_URL",
+        "postgresql+asyncpg://postgres@localhost/adcp",
+    )
+    engine = create_async_engine(db_url)
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    sm = async_sessionmaker(engine, expire_on_commit=False)
+
+    # Insert in FK-dependency order with explicit flushes so the
+    # accounts → buyer_agents → tenants chain commits correctly.
+    async with sm() as session:
+        async with session.begin():
+            session.add_all(
+                [
+                    Tenant(id="t_acme", host="acme.localhost", display_name="Acme Publishing"),
+                    Tenant(id="t_beta", host="beta.localhost", display_name="Beta Network"),
+                ]
+            )
+            await session.flush()
+            session.add_all(
+                [
+                    BuyerAgent(
+                        id="ba_acme_signed",
+                        tenant_id="t_acme",
+                        agent_url="https://signed-buyer.example/",
+                        display_name="Signed Buyer",
+                        status="active",
+                        billing_capabilities=["operator", "agent"],
+                        api_key_id=None,
+                    ),
+                    BuyerAgent(
+                        id="ba_acme_bearer",
+                        tenant_id="t_acme",
+                        agent_url="https://bearer-buyer.example/",
+                        display_name="Bearer Buyer",
+                        status="active",
+                        billing_capabilities=["operator"],
+                        api_key_id="dev-bearer-token-acme-1",
+                    ),
+                    BuyerAgent(
+                        id="ba_beta_suspended",
+                        tenant_id="t_beta",
+                        agent_url="https://suspended.example/",
+                        display_name="Suspended Buyer",
+                        status="suspended",
+                        billing_capabilities=["operator"],
+                    ),
+                ]
+            )
+            await session.flush()
+            session.add_all(
+                [
+                    Account(
+                        id="a_acme_1",
+                        tenant_id="t_acme",
+                        buyer_agent_id="ba_acme_signed",
+                        account_id="signed-buyer-main",
+                        name="Signed Buyer — Main",
+                        status="active",
+                        billing="operator",
+                    ),
+                    Account(
+                        id="a_acme_2",
+                        tenant_id="t_acme",
+                        buyer_agent_id="ba_acme_bearer",
+                        account_id="bearer-buyer-main",
+                        name="Bearer Buyer — Main",
+                        status="active",
+                        billing="operator",
+                    ),
+                ]
+            )
+
+    print("Seeded: 2 tenants, 3 buyer agents, 2 accounts.")
+    print("Hit: http://acme.localhost:3001/.well-known/agent.json")
+    print("Hit: http://acme.localhost:3001/mcp")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/v3_reference_seller/src/__init__.py

@@ -0,0 +1 @@
+"""v3 reference seller — Spec 3.0-compliant on the wire, 3.1-ready in arch."""