You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Add translate_universal_macros pinned to the shared compliance fixture #956
The Python SDK needs a producer-side universal-macro translation helper with behavior identical to @adcp/sdk. AdCP PR #6679 has now published the language-neutral fixture and ratified the previously open policy questions.
Add adcp.substitution.encode_unreserved(raw) -> str: UTF-8 encode and preserve only RFC 3986 unreserved bytes (ALPHA / DIGIT / - . _ ~), using uppercase %NN escapes.
Add adcp.substitution.translate_universal_macros(pixel_url, mapping) with Python-native typed mapping/result models. The result must include url, dropped_params, unmapped_macros, dropped_consent_macros, frozen_consent_macros, and suspect_native_values.
Execute the canonical fixture against the shipping helper. Load it from a pinned AdCP compliance artifact/test input; do not duplicate the expected-results table in Python.
Reject any native mapping containing U+0000–U+001F or U+007F before emitting a URL, including an unsafe unused mapping entry. Raise a typed error exposing fixture code unsafe_native_mapping and the offending macro.
When a consent macro is supplied through value, encode it normally and report it in frozen_consent_macros in mapping-property order, deduplicated. This is advisory, not a hard failure.
Normalize a bare trailing ? away and preserve all other fixture-defined query, path, fragment, single-pass, and diagnostic-ordering behavior.
The WG deliberately did not adopt broader C1/U+2028/U+2029/query-delimiter rejection, hard rejection of impression-scoped value mappings, or whole-translation failure for unmapped consent macros. Those earlier triage recommendations are superseded by DR-0012 through DR-0014.
Acceptance criteria
Every success and expected_error vector passes against the public Python helper.
The helper and result/error types are exported from the supported public package surface.
Unit tests retain only Python-specific mechanics outside the shared fixture suite.
Documentation and changeset describe the trust boundary and diagnostics.
Do not port the old expect_universal_macro_substituted storyboard assertion. DR-0005 places this non-wire-observable behavior in golden-fixture testing.
Classification: Feature request Bucket(s): none of the gated bucket labels (client/handlers/signing/validation/middleware/examples/docs/cross-repo) exist in this repo's label set — closest conceptual fit is core SDK surface (adcp.substitution, neighboring canonical_formats/pixel_tracker.py) plus a cross-repo fixture dependency. Applying enhancement only. Status: ready-for-human
What the experts said:
code-reviewer: shape is a clean, non-breaking addition, but "byte-for-byte" parity is unverifiable without the JS source or fixture — recommends splitting encode_unreserved (implement now, pure RFC 3986, zero ambiguity) from universal_macro_translation (block on fixture/JS reference).
dx-expert: return type should be a dataclass matching the pixel_tracker.py sibling pattern, not a bare dict; the privacy-macro guardrail needs to be a structured, returned advisory (or raise), not a docstring/warning that's easy to silence.
security-reviewer: flags this as security-sensitive — native values are inserted raw into URLs rendered across browsers/CTV by design with "no validation," and a value-mapped privacy macro (GDPR_CONSENT/US_PRIVACY/GPP_STRING) freezes one user's consent/device/geo data into a pixel reused across every subsequent impression. Both need fail-closed enforcement, consistent with this repo's existing scheme-allowlist precedent in pixel_tracker.py, not documentation alone.
ad-tech-protocol-expert: design is spec-consistent with the AdCP universal-macro enum already vendored in this repo, but the golden fixture this issue is pinned to (.context/universal-macro-translation.vectors.json) isn't recoverable from anywhere I have access to — implementing the translator against prose alone risks silent JS drift.
My take: Solid, spec-aligned design, but two independent reasons this isn't a routine hand-off: the security/privacy guardrails (native passthrough, build-time-vs-impression-time macro misuse) need fail-closed code rather than docs per existing repo precedent, and the actual cross-SDK fixture this is pinned to doesn't exist anywhere I can read. Splitting encode_unreserved (no external dependency) from universal_macro_translation (needs the fixture) looks like the cleanest path.
Can the .context/universal-macro-translation.vectors.json draft be recovered/re-attached, or pushed to adcontextprotocol/adcp so Python and JS can actually be checked against the same vectors?
Should universal_macro_translation fail-closed on native (reject control chars/CRLF and dangerous schemes) and raise — not just warn — when a known privacy/device/geo macro name is paired with value, matching pixel_tracker.py's existing trust-boundary posture?
OK to land encode_unreserved standalone now and gate universal_macro_translation on the fixture landing, rather than shipping both together against prose alone?
changed the title [-]Add universal_macro_translation + encode_unreserved (pinned to a shared golden fixture)[/-][+]Add translate_universal_macros pinned to the shared compliance fixture[/+]on Aug 19, 2026
Activity
bokelley commentedon Jun 20, 2026
Triage
Classification: Feature request
Bucket(s): none of the gated bucket labels (
client/handlers/signing/validation/middleware/examples/docs/cross-repo) exist in this repo's label set — closest conceptual fit is core SDK surface (adcp.substitution, neighboringcanonical_formats/pixel_tracker.py) plus a cross-repo fixture dependency. Applyingenhancementonly.Status: ready-for-human
What the experts said:
encode_unreserved(implement now, pure RFC 3986, zero ambiguity) fromuniversal_macro_translation(block on fixture/JS reference).pixel_tracker.pysibling pattern, not a bare dict; the privacy-macro guardrail needs to be a structured, returned advisory (or raise), not a docstring/warning that's easy to silence.nativevalues are inserted raw into URLs rendered across browsers/CTV by design with "no validation," and avalue-mapped privacy macro (GDPR_CONSENT/US_PRIVACY/GPP_STRING) freezes one user's consent/device/geo data into a pixel reused across every subsequent impression. Both need fail-closed enforcement, consistent with this repo's existing scheme-allowlist precedent inpixel_tracker.py, not documentation alone.universal-macroenum already vendored in this repo, but the golden fixture this issue is pinned to (.context/universal-macro-translation.vectors.json) isn't recoverable from anywhere I have access to — implementing the translator against prose alone risks silent JS drift.My take: Solid, spec-aligned design, but two independent reasons this isn't a routine hand-off: the security/privacy guardrails (native passthrough, build-time-vs-impression-time macro misuse) need fail-closed code rather than docs per existing repo precedent, and the actual cross-SDK fixture this is pinned to doesn't exist anywhere I can read. Splitting
encode_unreserved(no external dependency) fromuniversal_macro_translation(needs the fixture) looks like the cleanest path.Open questions for @bokelley:
.context/universal-macro-translation.vectors.jsondraft be recovered/re-attached, or pushed toadcontextprotocol/adcpso Python and JS can actually be checked against the same vectors?universal_macro_translationfail-closed onnative(reject control chars/CRLF and dangerous schemes) and raise — not just warn — when a known privacy/device/geo macro name is paired withvalue, matchingpixel_tracker.py's existing trust-boundary posture?encode_unreservedstandalone now and gateuniversal_macro_translationon the fixture landing, rather than shipping both together against prose alone?Triaged by Claude Code. Session: https://claude.ai/code/cse_017hA41XWeTJS9X2nyoeZaxZ
Generated by Claude Code
test(creative): add universal_macro_translation cross-SDK conformance…
[-]Add universal_macro_translation + encode_unreserved (pinned to a shared golden fixture)[/-][+]Add translate_universal_macros pinned to the shared compliance fixture[/+]