docs(compliance): name the verifiability gap and the SDK bridge's role (#4593)#4619
Merged
Conversation
#4593) Adds a "Test surfaces and the verifiability gap" section to the comply_test_controller doc, framing the gap as universal across seller classes. State-local sellers close it via DB-backed `seed_*`; upstream-proxy sellers close it via the SDK's `TestControllerBridge`. The bridge is one implementation of the test-surface pattern, not a separate seller category. Documents the non-normative `_bridge` marker (shipped in adcp-client#1786) as the response-level signal runners read to distinguish fixture-merged content from upstream-derived content, and adds a three-axis table covering test mode, the `account.sandbox` flag, and bridge participation. Closes #4593. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
3 tasks
…expert feedback Restructures PR #4619 in response to convergent DX/docs/product/protocol-expert review: - Canonical home for the framing is `conformance.mdx`, not the L3 controller page. The audience for this framing (DSP/SSP engineers, RMN proxy implementers, procurement leads reading badge docs) is broader than the audience for the controller tool definition. - Drops the "live behavior" wording to avoid re-importing the deprecated (Live) framing rejected in #4379 — (Sandbox) attests sandbox-flag tolerance on prod, not adapter-to-upstream calls. - "Three orthogonal axes" → "Three signals — don't conflate them" so the table doesn't collide with the (Spec)/(Sandbox) "two axes" language already load-bearing in `conformance.mdx` and `aao-verified.mdx`. - "Test mode" axis label → "Test controller availability" to disambiguate from BidRequest-style test flags an OpenRTB reviewer would expect. - Defines "state-local sellers" and "upstream-proxy sellers" inline on first use (SSPs/creative-agents; DSPs/retail-media/signals-brokers). - Pins the leading-underscore convention for SDK/runner-stamped metadata reserved for testing tooling, so future SDK fields can't pollute the wire surface without going through the same gate. - Leaves a short pointer on the L3 controller page back to the canonical section, and adds a reciprocal hook in `aao-verified.mdx`'s existing controller-relationship Note. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #4593. Documents the test-surface pattern, the SDK's
TestControllerBridge, the non-normative_bridgeresponse marker, and the three runtime signals adopters routinely conflate (test controller availability,account.sandbox,_bridge).Where the content lives
The canonical home is the Conformance Specification — that's the audience that needs this framing (DSP/SSP engineers, RMN proxy implementers, procurement leads reading badge docs). The L3 controller page keeps a short pointer; the AAO Verified page cross-links into it from the existing controller-relationship Note.
docs/building/verification/conformance.mdx_bridgemarker description, leading-underscore convention pin, and the three-signal disambiguation table.docs/building/by-layer/L3/comply-test-controller.mdxdocs/building/verification/aao-verified.mdx<Note>pointing into the conformance.mdx section..changeset/4593-test-surfaces-verifiability-gap.mdFraming decisions (expert review fed back in)
(Spec)/(Sandbox). Those qualifiers carry settled history in RFC: Verified (Sandbox) — reframe Verified (Live) to attest production-surface sandbox tolerance instead of canonical-campaign delivery #4379 and spec(conformance): AAO Verified mark via continuous delivery observability (transitional) #3001; this PR sits underneath that taxonomy.(Live)framing RFC: Verified (Sandbox) — reframe Verified (Live) to attest production-surface sandbox tolerance instead of canonical-campaign delivery #4379 rejected —(Sandbox)attests sandbox-flag tolerance on prod, not adapter-to-upstream calls. The new section talks about the test-surface pattern (closing the storyboard loop), not "live behavior."(Spec)/(Sandbox)framing in the same doc.BidRequest.test=1-style request flags an OpenRTB reviewer would expect._marks SDK/runner-stamped metadata reserved for testing tooling. Future SDK fields follow the same rule, so the wire surface doesn't get polluted by new conveniences inventing_trace,_origin, etc.Test plan
npm run check:owned-links— passesnpm run test:docs-nav— 15/15 pass🤖 Generated with Claude Code