feat(decisioning): MockAdServer Protocol + /_debug/traffic counters for anti-façade compliance

[bokelley]

Context

Adopter platform methods that return empty without calling anything (e.g. sync_creatives → [], get_media_buy_delivery → []) violate AdCP's anti-façade contract introduced in adcp PR #3816. Today there is no machine-checkable way to assert "this method actually made a downstream call to the ad server" — storyboard runs pass even when the platform is a no-op.

Cross-link: existing issue #347 (upstream-traffic recorder middleware) — this issue is the platform-side bookend. #347 records HTTP traffic the SDK emits; this issue records the calls the platform attempts to make to the ad server.

Refs:

• examples/v3_reference_seller/src/platform.py
• adcp PR #3816 (anti-façade contract)

Acceptance Criteria

• MockAdServer Protocol (or ABC) defined in the decisioning toolkit — the contract every platform method should call into for upstream operations (push creative, push media buy, fetch delivery, etc.)
• Default impl with traffic counters (per-method call count, last-call timestamp, last-call args)
• /_debug/traffic endpoint exposes the counters, gated behind a debug flag
• V3 reference seller's platform.py rewired to call the MockAdServer for every spec operation
• Storyboard runner can assert traffic.sync_creatives.call_count >= 1 after a sync_creatives storyboard
• Cross-linked to feat(testing): reference upstream-traffic recorder middleware for query_upstream_traffic adopters (adcp#3830 item 4) #347 in description

[bokelley]

Triage

Classification: Feature request
Bucket(s): handlers, examples (neither label exists in this repo — flagged in run summary)
Status: ready-for-human

What the experts said:

• code-reviewer: Two blockers — /_debug/traffic has no HTTP route-registration path in the FastMCP/Starlette stack; per-method counter increments are a data race under ThreadPoolExecutor sync dispatch.
• dx-expert: MockAdServer will be read as test-only by adopters and agents — follow the TaskRegistry/InMemoryTaskRegistry pattern (AdServerClient / InMemoryAdServerClient). Storyboard assertion path (in-process call_count() vs. /_debug/traffic) must be decided before coding starts.
• security-reviewer: Two HIGH findings — per-method counters have no account_id scoping so last-call args are readable cross-tenant; /_debug/traffic will not inherit MCP ed25519/Bearer auth when registered as a plain HTTP route.

My take: The anti-façade recording goal is sound and fully implementable once four design decisions land. All blockers are fixable without scope reduction; none require rethinking the core mechanism.

@bokelley — four decisions needed before this can execute:

1. Naming: AdServerClient / InMemoryAdServerClient (mirrors the TaskRegistry/InMemoryTaskRegistry split already in this codebase)?
2. Assertion path: in-process platform.ad_server.call_count("sync_creatives"), or /_debug/traffic? Both are implementable but require different plumbing.
3. Counter scoping: per account_id to prevent cross-tenant reads through the debug endpoint?
4. Endpoint auth: reuse _is_production_env() gate + explicit BearerTokenAuthMiddleware registration (same pattern as InMemoryTaskRegistry production gate)?

---

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

---

Generated by Claude Code