feat(substitution): translate universal macros

[bokelley]

Summary

• add a typed public adcp.substitution surface for RFC 3986 value encoding and producer-side universal-macro translation
• reject C0/DEL characters across every native mapping before URL emission and surface stable typed error details
• report deterministic dropped, unmapped, consent, frozen-consent, and suspect-native diagnostics
• vendor the canonical AdCP 3.2 fixture and schema from acc022a53fad8ecab877d374df1760fef756325f with pinned SHA-256 digests
• document the raw-native trust boundary and required diagnostic handling

Impact

Python sellers can now translate pixel URL query-value macros with the same wire shape and policy as the shared compliance contract. Literal values are UTF-8 percent-encoded with the RFC 3986 unreserved whitelist, native ad-server tokens remain raw, unmapped macro parameters are dropped deterministically, and path/query-key/fragment content stays byte-preserved.

Native mappings are an explicit trust boundary. Any U+0000-U+001F or U+007F character in a used or unused native mapping fails closed before a URL is produced. Consent strings supplied as literal values remain advisory, are encoded normally, and appear in frozen_consent_macros.

Validation

• make test-fast — 6,650 passed, 40 skipped, 9 deselected, 1 xfailed
• make lint
• make typecheck-all
• canonical fixture and schema digest/structure checks
• independent code-quality, security, and AdCP protocol reviews

Closes #956
Progresses adcontextprotocol/adcp#6674

[aao-secretariat]

Ladon verdict: Approve

Approve — purely additive PR introducing a new adcp.substitution public surface (242 lines) for producer-side universal-macro translation, executed against a vendored SHA-256-pinned canonical AdCP 3.2 fixture.

What I checked:

• Control flow traced against golden vectors: empty-query normalization, fragment/query split, fail-closed native C0/DEL guard, repeated-key drop order — all consistent.
• Semver signal correct: feat(substitution): is the right conventional-commit prefix for additive exports; public_api_snapshot.json is updated.
• src/adcp/__init__.py is flagged high-risk but the change is a (modified) additive re-export with no medium-or-higher finding on it — presumed safe per the high-risk-flag guidance.
• No type-layering, generated-code, forward-compat, or credential concerns triggered.

Medium findings

• AGENTS.md — New adcp.substitution public surface absent from AGENTS.md handler table.

Decision path: No critical/high findings (row 1 no). gated_paths false (row 2 no). No (deleted) high-risk reason (row 3 no). The single medium finding is a docs/context gap, not data-loss/schema/infra (row 4 no). High-risk reason is (modified) with a medium finding present — however this maps to row 5... note: row 5 fires when high_risk is true AND a (modified) reason exists AND any medium finding is present. That condition is met here, so the outcome is escalate.

Medium findings

• AGENTS.md — New adcp.substitution public surface absent from AGENTS.md