feat(compliance): unified anti-façade + cascade-attribution contract (#3813)

[bokelley]

Closes #3785, closes #3796. Tracking issue: #3813.

Replaces the two partial-ship spec PRs (#3795, #3798) with a single coherent contract change.

Why this PR exists, not the original two

The original plan was: ship #3795 (sales_social payload variety, items 1 & 2 from #3785), ship #3798 (capture/substitution output shapes from #3796), defer #3785 item 3, file a runner-side issue for the cascade fix, and audit the other 18 storyboards in a follow-up.

That plan was theatrical:

• Items 1 & 2 only raise the façade bar slightly — adapters can still pass with smarter fakes (fabricate uploaded_count and action). Item 3 (cross-step upstream side-effect assertion) is the actual contract.
• fix(compliance): define capture_path_not_resolvable / unresolved_substitution output shapes #3798 ships a contract on paper — runners don't emit the codes, so the user-visible symptom from Storyboard runner: stateful step cascade silently skips downstream steps when prior response is shape-valid but missing extractor-required fields #3796 isn't fixed. The signals[0]/signals[1] field_present guards fix(compliance): define capture_path_not_resolvable / unresolved_substitution output shapes #3798 added are workarounds, not the fix.
• Auditing 18 storyboards for items-1-and-2-style enrichments before item 3 lands is busywork that gets reworked.

This PR collapses all of it into one ship.

What's in this PR

Spec contracts

runner-output-contract.yaml v1.1.0 → v2.0.0

• Three new validation_result.check codes:
  • capture_path_not_resolvable (synthesized) — the cascade-attribution fix from Storyboard runner: stateful step cascade silently skips downstream steps when prior response is shape-valid but missing extractor-required fields #3796. Emitted on the capturing step when context_outputs resolves to absent / null / "".
  • unresolved_substitution (synthesized) — pre-wire failure on a consumer step. request / response / json_pointer carve-outs.
  • upstream_traffic (authored) — the load-bearing anti-façade contract from Storyboards are façade-permissive: payload variety doesn't force adapters to confront upstream contracts #3785 item 3.
• Full expected / actual / json_pointer semantics per code.
• run_summary attribution notes — capture failures contribute to steps_failed, downstream consumer skips to steps_skipped with prerequisite_failed. upstream_traffic against an adopter that doesn't advertise query_upstream_traffic grades not_applicable, not failed.

storyboard-schema.yaml

• New upstream_traffic check kind documented with full semantics: min_count, endpoint_pattern, payload_must_contain (path + match), buyer_identifier_echo: true shorthand (the strongest single anti-façade signal — placeholder hashes don't match the storyboard's supplied vectors), since: prior_step_id for cumulative-effect assertions.
• context_outputs runner-behavior strengthened to cover absent / null / "" cases.
• capture_path_not_resolvable and unresolved_substitution descriptions expanded with output-shape cross-references.

comply-test-controller-request.json / comply-test-controller-response.json

• New query_upstream_traffic scenario on the existing comply_test_controller. Optional since_timestamp, endpoint_pattern, limit params.
• New UpstreamTrafficSuccess response branch with recorded_calls[] (method / endpoint / url / host / path / payload / timestamp / status_code) plus total_count / truncated / since_timestamp.
• Reuses the existing test-controller mechanism rather than introducing a separate /_debug/traffic URL — same auth, same sandbox-only gating, same list_scenarios discovery, same INVALID_PARAMS / UNKNOWN_SCENARIO error envelope.

Storyboard adoption (5 exemplars)

• sales-social: realistic add[] with hashed identifiers on sync_audiences; user_match on log_event with the matching hash; value/currency moved into custom_data (schema-routing fix — additionalProperties: true was silently swallowing them at the wrong nesting level); upstream_traffic assertions on both steps with buyer_identifier_echo.
• audience-sync: upstream_traffic on create_audience with buyer_identifier_echo and payload_must_contain for hashed_email.
• signal-marketplace: upstream_traffic on activate_on_platform with since: search_by_spec window and payload_must_contain for segment_id (the cascade case from Storyboard runner: stateful step cascade silently skips downstream steps when prior response is shape-valid but missing extractor-required fields #3796 — once runners emit capture_path_not_resolvable per the new contract, the signals[0]/signals[1] guards fix(compliance): define capture_path_not_resolvable / unresolved_substitution output shapes #3798 added become unnecessary; this PR doesn't add them).
• sales-non-guaranteed: upstream_traffic on create_media_buy (platform-agnostic POST count assertion).
• creative-ad-server: upstream_traffic on build_creative (platform-agnostic POST count assertion).

Mechanical rollout to the remaining 7 applicable specialisms (sales-guaranteed, sales-broadcast-tv, sales-catalog-driven, sales-proposal-mode, signal-owned, creative-template, creative-generative) follows in a separate PR. Not theatrical: the contract is fully defined, runner has a complete target, and these 7 will copy the pattern from the 5 exemplars verbatim.

Sibling-repo work needed (adcp-client)

The runner side of #3796 — emitting capture_path_not_resolvable and unresolved_substitution per the new contract — and the runner side of #3785 item 3 — implementing upstream_traffic by querying comply_test_controller's new query_upstream_traffic scenario — both land in adcp-client as one runner PR.

Until that PR ships:

• Storyboards declaring upstream_traffic will grade not_applicable against runners that don't yet implement the check (acceptable forward-compat).
• The cascade silent-skip described in Storyboard runner: stateful step cascade silently skips downstream steps when prior response is shape-valid but missing extractor-required fields #3796 still happens in field runs against the old runner — fix lands when adcp-client ships.

Non-breaking justification

• New validation_result.check enum values: additive.
• New query_upstream_traffic scenario: additive (scenarios enum is open-for-extension per response schema description).
• Storyboard validations: new check entries on existing steps; existing checks unchanged. Storyboards that previously passed continue to pass on adopters that don't advertise the new scenario.
• v2.0.0 bump on runner-output-contract.yaml reflects the new normative shapes runners MUST emit; runners conforming to v1.1.0 do not regress, they grade not_applicable for the new codes.

Verification

• node scripts/build-compliance.cjs passes all 9 lint stages and builds 22 universal / 6 protocols / 19 specialisms.
• npx vitest run tests/unit/comply-test-controller.test.ts passes (42/42).
• Pre-commit hook (typecheck + unit tests + state-change lint + dynamic imports) passes.

🤖 Generated with Claude Code

[bokelley]

Three-expert review applied (commit 0ac2702)

Ran the PR through ad-tech-protocol-expert, adtech-product-expert, and security-reviewer. Three HIGH security findings + six MEDIUM findings addressed inline; five LOW-priority items filed as #3830.

HIGH (security — block ship until fixed):

• ✅ Cross-caller traffic leakage: query_upstream_traffic MUST scope to requesting principal; multi-tenant sandboxes MUST key on auth principal.
• ✅ Headers via additionalProperties: true: flipped to additionalProperties: false on recorded_calls[] items so adopters can't dump Authorization: Bearer <token>.
• ✅ Redaction-by-reference broken: secret-key redaction obligation moved inline into the response schema description (the cross-file reference didn't transitively bind the controller-side adopter).

MEDIUM (fix before public conformance):

• ✅ rendered_output_fencing extended to cover note, description, skip_result.detail, and response.payload for upstream_traffic. Inversion rule documented: any field copied from storyboard / agent / adopter-controller MUST be fenced.
• ✅ buyer_identifier_echo: boolean → identifier_paths: [string]. Vibe contract replaced with explicit path enumeration. Also addresses the naming concern (was overloading "buyer" — identifier is supplied by the storyboard, fires on either side).
• ✅ JSONPath syntax pinned to dotted-with-[*] form only; RFC 9535 descendant ($..foo) explicitly NOT supported. Aligns with parsePathWithWildcards in @adcp/sdk per Storyboard conformance: required-clean allowlist + errors[*] predicate + pre-commit gate #3803 item 2.
• ✅ recorded_calls[].content_type added (required) so runners pick the right matcher deterministically. JSONPath valid only on application/json / *+json; non-JSON falls back to substring for match: present, grades not_applicable otherwise.
• ✅ since_timestamp boundary defined: inclusive lower bound, runner's wall clock at AdCP-request-issue time, 50–250ms clock-skew tolerance, controller timestamps monotonically non-decreasing reflecting send time.
• ✅ Threat-model framing made explicit: contract raises the bar against unintentional façades (LLM-generated synthetic-placeholder adapters), NOT an adversarial integrity check. Spec consumers MUST NOT present passing as cryptographic proof.

Schema tightening:

• ✅ since_timestamp moved to required in UpstreamTrafficSuccess.
• ✅ payload capped at maxLength: 65536 with truncation guidance — prevents MB-scale recorded payloads from bloating LLM-rendered compliance reports.
• ✅ Hashed-PII test-mode framing: adopters MUST NOT enable query_upstream_traffic against sandboxes processing production identifier values.

LOW (deferred — filed as #3830):

• Build-time storyboard check enum lint (catches typos that would silently grade not_applicable).
• payload_attestation digest mode for EU / privacy-conscious adopters.
• purpose / category tagging on recorded_calls (separates platform-primary calls from measurement-vendor calls).
• Reference upstream-traffic recorder middleware (@adcp/sdk/upstream-recorder, adcp.testing.upstream_recorder).
• Advisory-only storyboard pre-runner so adopters can validate instrumentation before high-stakes adoption flips the switch.

v2.0.0 bump confirmed proportional by ad-tech-protocol-expert (new MUST clauses change runner conformance — semver isn't about diff size).

Build green; CI checks should re-run on the push.

[bokelley]

Candidate runner-side implementation of the v2.0.0 contract is up for review at adcontextprotocol/adcp-client#1289 (closes adcontextprotocol/adcp-client#1253). All four behaviors land — forward-compat default, capture_path_not_resolvable synthesis, unresolved_substitution synthesis, and the upstream_traffic check (with comply_test_controller's query_upstream_traffic pre-fetched once per since_timestamp window so the runner's synchronous validator stays sync). 18 dispatcher-level unit tests; type-check / build / lint clean; baseline storyboard suite green.

Multi-expert review (protocol / code / security / testing) surfaced a clean separation between "implementation drift against this spec PR" and "spec-side ambiguities worth pinning before merge":

Implementation tracks an earlier draft of this spec PR — fixing in adcp-client#1289 before merge:

• buyer_identifier_echo: boolean → identifier_paths: string[] (the explicit-enumeration replacement).
• actual.identifier_echo_failures → actual.missing_identifier_values (diagnostic-summary key rename).
• Missing content_type field on recorded_calls[] and the JSON-only path-matching gate (substring fallback for match: present, not_applicable for equals/contains_any against non-JSON payloads).

Spec-side ambiguities the implementation surfaced — worth pinning here before this PR merges:

• endpoint_pattern glob grammar undefined. Examples use POST * and POST */audience/upload, but does * cross /? Is ? a wildcard? My implementation treats * as .* (greedy, /-crossing) and escapes everything else literally — most permissive interpretation. Worth pinning in the comply-test-controller-request.json endpoint_pattern description so adopters and runners can't disagree.

• $.. descendant in payload_must_contain.path. The storyboard-schema patch says $.. is NOT supported, but the controller-response side prose ("recorded_calls[].payload contains hashed_email at any depth") uses $..-shape descriptions. Spec is internally inconsistent — drop the descendant operator, or allow it. Pick one.

• identifier_paths resolution against arrays. Spec says runners extract values at the paths and assert each value appears in at least one matching recorded_call's payload at any depth — but doesn't define whether all resolved values must be echoed (anti-façade-faithful: a single placeholder satisfies it) or any (lenient). The whole point of the contract is detecting fabricated placeholders, so I'd recommend all — but that's a load-bearing semantic the spec should pin explicitly.

• since_timestamp clock-skew posture. My runner sends new Date().toISOString() raw as the lower bound. A controller that records a call before its server clock advanced past the runner's since_timestamp could legitimately drop a call from the window. Worth a runner SHOULD subtract a 250ms tolerance note in the contract, or an explicit "controllers MUST treat since_timestamp as inclusive of any call recorded within the same wall-clock millisecond" — either pins the boundary, but unspecified is the worst case.

Reviewers welcome on adcontextprotocol/adcp-client#1289. The runner implementation gives the spec a candidate to validate against — if any of the spec's prose is ambiguous about a behavior the runner had to pick, that's exactly what the implementation should surface back.

[bokelley]

Cross-talk note: my 16:18 comment crossed your spec-side resolution at commit 0ac27028e — most of what I flagged was already resolved. SDK-side fix-up just landed at adcontextprotocol/adcp-client@fd0c6fc0 (PR adcontextprotocol/adcp-client#1289), now aligned with the current spec PR shape:

• identifier_paths: string[] replaces buyer_identifier_echo: boolean. Anti-fabrication semantics are explicit: ALL resolved values must echo, not just any one.
• missing_identifier_values (was identifier_echo_failures) on actual.
• recorded_calls[].content_type (required) carried through, with JSON-only path-matching gate. Non-JSON match: present falls back to substring search of the path's terminal key against the raw payload string. Non-JSON match: equals / contains_any grade not_applicable. The whole validation grades not_applicable only when every declared path downgraded that way.
• RFC 9535 descendant operator ($..) explicitly removed from the JSONPath-lite resolver per the spec's pin.
• 250 ms clock-skew tolerance subtracted from since_timestamp before sending to the controller.
• query_upstream_traffic query is principal-scoped (per the spec patch's recorded_calls security fix the SDK now consumes — adopters returning 4xx for cross-tenant principals will surface as standard controller errors).

Plus three SDK-side bugs the multi-expert review caught and the spec PR doesn't bear on:

• globToRegExp: ? was escaping as a 0-or-1 quantifier; now treated as a literal.
• applyContextOutputs (non-provenance form) now drops "" too — was silently divergent from the provenance form.
• Unknown since: prior_step_id now grades failed loudly (was silently widening to current step's window).

SDK PR ready for review when you are. Tests cover the dispatcher (25 tests) plus runner-integration via stubbed runStoryboardStep / runStoryboard (8 tests), including the capture-failure → consumer-skip cascade pinned end-to-end. Type-check / lint / build clean.

Two open spec-side ambiguities the implementation surfaced that I couldn't find resolved in 0ac27028e — flagging in case they're worth pinning before this merges:

1. Non-JSON match: present substring needle. Spec says "fall back to substring matching for match: present against the raw string" but doesn't specify what substring. The path string itself (users[*].hashed_email) won't appear in form-urlencoded bodies. The implementation extracts the path's terminal alpha key (hashed_email) — defensible best-effort downgrade, but worth pinning explicitly so other runners agree.

2. endpoint_pattern glob grammar. Examples use POST */audience/upload and POST *. Implementation: * → .* (greedy, /-crossing); all other regex metas escaped literally (including ?). Worth a one-line note in the comply-test-controller-request.json endpoint_pattern description so adopters and runners can't disagree.

Both could be follow-up patches against 0ac27028e or filed against #3830 — either works.