epic(client): close gaps with JavaScript SDK v13

[bokelley]

Context

JavaScript @adcp/sdk@13.0.0 tightened several adopter-facing boundaries. Python SDK 7 already has canonical creatives, three-arm media-buy responses, tenant-scoped references, raw-body signature verification, SSRF-safe delivery, and AdCP 3.1.15 schemas. This issue tracks the remaining useful parity work without importing experimental AdCP 3.2 behavior into the stable surface.

First batch — #1032

• Fail closed when the legacy ADCPClient receives an unsigned MCP webhook without a configured secret; retain an explicit, literal, per-agent isolated-network compatibility escape. This is intentionally classified as breaking and documented in the 7→8 migration guide.
• Process the authenticated webhook body rather than a separately supplied object, and keep tokens/results out of activity telemetry.
• Export a real 20-member AssetInstance union, AssetInstanceType, and all registry-backed variants through stable Python names without reviving removed pre-4.0 aliases.
• Add fresh brand lookup and structured, bounded registry HTTP error metadata, including header and JSON-body retry guidance.
• Correct AdCP 3.1.15 release documentation and make migration guides discoverable from package metadata/PyPI.

Follow-up batches

• Design a per-call TaskOptions surface with one absolute deadline spanning discovery, capability/version preflight, dispatch, and postflight; preserve separate transport idle/read timeouts and attach retry-recovery metadata for mutating calls.
• Enforce streaming registry response-size limits (256 KiB default, 2 MiB for bulk/feed endpoints) before buffering response bodies.
• Define a typed/allowlisted registry error-detail envelope before projecting errors from authenticated write endpoints into logs or agent context.
• Evaluate optional OpenTelemetry spans and trace propagation with a no-op default.
• Design buyer-side OAuth discovery and authorization-code/PKCE helpers with state binding and SSRF-safe metadata retrieval.
• Revisit proposal-negotiation APIs only after AdCP 3.2 is a signed stable release.

Non-goals

• Do not duplicate the JavaScript canonical storyboard runner; Python CI can continue invoking the shared runner.
• Do not expose experimental AdCP 3.2 schemas through Python's stable public API yet.

[bokelley]

Triage

Classification: Epic / tracking
Bucket(s): client, signing, docs (no exact repo labels found — gap noted)
Status: ready-for-human

What the experts said:

• security-reviewer: Item 1 (unsigned webhook fail-close) is a hard breaking change — existing deployments that omit webhook_secret will begin failing on every webhook. The escape-hatch design matters: a plain boolean flag is too easy to silence unthinkingly; recommend a named sentinel class. Also flags a replay-protection gap in the legacy ADCPClient path that the design doc should acknowledge. Human review required before any PR.
• ad-tech-protocol-expert: Confirmed epic-shaped; first batch alone spans four distinct change surfaces (security behavior inversion, multi-layer type-system export, new exception class + registry method, docs) and realistically takes 2+ weeks. Items 2–4 are non-breaking additions (asset alias exports, RegistryError structured fields, PyPI/docs metadata) safe for future authorized PRs. Item 1 is breaking. Follow-up batch deferral is correct; buyer-side OAuth is 3.1.x-feasible but deferring for scope is fine.

My take: The epic structure is sound, but Item 1 (webhook fail-close) needs a design decision on the escape-hatch API before any implementation starts — specifically whether to use a sentinel class rather than a boolean to make insecure configurations auditable. Items 2–4 can be authorized individually with /triage execute once the escape-hatch design is settled. Recommend converting this issue to a GitHub Project epic or task list to track batch progress; do not split into peer issues.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01EnJgNDp1yNjJhux8tN1FNH

---

Generated by Claude Code