Spec convention for compliance-mode requests (distinct from X-AdCP-Sandbox-Mode)

[bokelley]

Summary

Sandbox mode and compliance-test mode are different concerns, but today both are conflated under `X-AdCP-Sandbox-Mode: on`. This creates ambiguity for adopters who want to:

• Run the compliance storyboard against a real seller deployment (production-shaped, with real DBs, real adapters) without polluting production state — "compliance against production-mode"
• Run a buyer's integration tests against a sandboxed seller surface that auto-approves everything — "buyer testing against sandbox-mode"

Today both modes hit the same code path. Sellers can't tell which case applies. Compliance runners can't reliably opt into auto-approval (or any other compliance-friendly behavior) without breaking sandbox-mode semantics for non-compliance traffic.

Concrete pain (today's session)

We spent significant time debugging storyboard failures that turned out to be:

• Seller's manual-approval gate intercepting before `canceled=true` reached the cancel branch
• Seller's INVALID_DOMAIN gate rejecting RFC 2606 example domains
• Both legitimate for production; both blockers for compliance validation

Workaround: flip seller tenant config to "auto-approve everything" before running the storyboard. But that means we're not actually testing the seller-as-deployed; we're testing a stripped-down compliance variant.

A spec-blessed compliance-mode header would let:

• The storyboard runner identify itself as a compliance test
• The seller opt into compliance-friendly behavior (auto-approve, deterministic IDs, bypass domain blocklists, etc.) ONLY for compliance traffic, without changing production-or-sandbox-buyer behavior
• The seller report compliance test results without polluting production audit trails

Proposed header

`X-AdCP-Test-Mode: compliance` (or `X-AdCP-Compliance-Run: true`)

Semantics: "this request is part of an automated compliance suite. Seller MAY apply compliance-friendly defaults (auto-approve gated operations, accept reserved-TLD domains, etc.) without violating production safety. Sellers that don't recognize the header behave normally — no compatibility burden."

Capability advertisement: `get_adcp_capabilities` could include a `compliance_mode` block describing which gates the seller will bypass.

Why this is different from sandbox

• Sandbox = "non-production state, fake money/inventory, but real seller behavior including all gates." Useful for buyer integration testing where you want to validate gate handling.
• Compliance = "running the compliance storyboard, please don't make me fight your config." Useful for spec validation where gates are off-topic.

Both have legitimate use cases. They shouldn't be the same header.

Related

• adcp#4357 (capability-declared scenarios) — overlaps if compliance-mode capabilities are advertised
• fix(media-buy): update_media_buy(canceled=true) returns success but doesn't persist cancel bokelley/salesagent#324 (the manual-approval gate that masked PR Hide billing button until user subscribes, move membership to top #321)

[bokelley]

Triage

Classification: Feature request (new protocol convention)
Bucket(s): spec/protocol, compliance-suite
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: Two blockers — (1) sandbox.mdx is explicit: "Sellers MUST NOT alter behavior based on [X-* headers]. Sandbox mode is determined solely by the account reference." A new X-AdCP-Test-Mode header reintroduces exactly what was normatively removed. (2) The header carries no identity binding; any buyer can send it to bypass a seller's production approval gates, with no cryptographic anchor to the AAO compliance runner's identity. OpenRTB addressed the same problem by moving test signals to the application layer (test: 1 in the bid request). Non-breaking and additive — only positives.
• adtech-product-expert: If Proposal: storyboard runner is approval-workflow-aware; sellers advertise per-operation approval policy via get_adcp_capabilities #4357's sandbox.auto_approve_all lands, sandbox accounts already get gate-bypass; the header only adds value against production-shaped deployments — exactly where unbound gate-bypass is a governance risk. Audit-trail separation is a legitimate concern worth preserving. The right home is the comply_test_controller machinery, where auth model and scoping are already governed.

My take: Experts converge: the pain is real and well-documented, the mechanism conflicts with the protocol's own normative text on mode signaling. @bokelley, your call: fold compliance-mode activation into #4357 as a comply_test_controller extension (Option B — governed, session-scoped, no new header family), or accept the header with an explicit trust-model amendment (Option A — simpler for runners, normatively inconsistent with sandbox architecture). Both issues should resolve together in a single WG pass.

Option A — New header (as proposed):

X-AdCP-Test-Mode: compliance

Seller MAY bypass gates for flagged requests. Non-adopters ignore it silently; storyboard may still fail against them.

Option B — comply_test_controller scenario (WG alternative):

{
  "scenario": "set_compliance_mode",
  "params": { "enabled": true, "gates": ["domain_blocklist", "manual_approval"] }
}

Seller advertises set_compliance_mode in compliance_testing.scenarios[]. Mode is session-scoped, governed by the controller's existing auth model. All test-mode signaling stays inside one machinery; no new header family.

---

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code