feat: make canonical creatives the primary SDK contract

[bokelley]

Context

The TypeScript SDK has made canonical creatives the primary contract in adcontextprotocol/adcp-client#2391. The reference implementation is merged and published as @adcp/sdk@13.0.0-rc.3; Python implementation is no longer gated on waiting for a TypeScript RC.

This is broader than the v1↔v2 projection layer completed in #741 and the comparison helpers completed in #885. Adopting the modern Python SDK must mean application code uses format_kind, format_options, and format_option_refs, while {agent_url, id} creative identity is confined to wire adapters and explicitly named migration APIs.

Target release

• Target Python SDK 7.0.0-rc before GA.
• Treat the public-surface changes as semver-major.
• Keep negotiated AdCP protocol versions distinct from the Python package version in code, docs, and diagnostics.

Required public contract

• Make canonical creative-bearing models the unqualified/default public types for products, packages, creatives, media-buy requests/responses, delivery responses, and server handler payloads.
• Move raw {agent_url, id} shapes behind Legacy* model names and explicitly named legacy client/server methods. Follow the cross-SDK Legacy* convention; do not introduce AgentUrl* names.
• Make list_creative_formats legacy-only. Canonical discovery is through product format_options and canonical declarations.
• Remove format_ids from canonical Product and creative-filter models.
• Make generic execute_task, multi-agent APIs, callbacks, response builders, server helpers, and asset helpers canonical by default. Any raw-format variant must be explicit and legacy-named.
• Root Format must mean a canonical format declaration, not the generated named-format model.
• FormatId must not be available from the normal adcp root import. Expose legacy identity only as LegacyFormatId or through an explicit legacy/raw module.
• Primary discovery and write methods must be canonical across get_products, create_media_buy, update_media_buy, sync_creatives, list_creatives, media-buy reads, and creative-delivery reads.
• Preserve raw wire access for migration/conformance tooling through conspicuous legacy methods, hard-deprecated for removal with AdCP 4.0.
• Generated/raw protocol modules may remain available for wire tooling, but must not be primary application-facing imports.

Runtime Pydantic invariants

These are runtime requirements, not typing-only or documentation-only constraints:

• For every primary model, model_json_schema() must recursively contain no property named format_id, format_ids, or format-scoped agent_url, including nested definitions, unions, aliases, request/response containers, callback payloads, and server payloads.
• For every primary model, model_dump() and JSON serialization must be incapable of emitting those fields at any nesting depth, including when input was constructed from legacy/raw objects, aliases, extras, or nested generated models.
• Tests must walk the complete primary schema and serialized value recursively. A top-level assertion or static type check is insufficient.

Wire negotiation and lifecycle boundaries

• Apply one capability matrix consistently:
  • AdCP 3.0: legacy wire; upgrade reads and downgrade writes.
  • AdCP 3.1: the version alone is not canonical evidence; use media_buy.features.canonical_creatives, then request-local schema evidence where available, otherwise fail closed unless an unambiguous legacy projection exists.
  • AdCP 3.2+: canonical by contract; canonical_creatives: false is a capability error.
• Use the same effective converter and canonical response boundary for polling, task continuation, input-required flows, async completion, callbacks, and webhooks.
• For server/framework APIs, normalize legacy inbound requests before adopter handlers and project responses back to the caller's captured negotiated dialect.
• Keep network resolution outside the pure projector. Feed it validated, cached catalog snapshots in precedence order (publisher → approved community mirror → agent-derived/configured).
• Keep catalog lookup URL-sensitive, including explicit historical AAO aliases and AdCP URL canonicalization while preserving path/query scope.
• Snap's canonical mirror declarations remain canonical-only unless an exact owner-sensitive v1_format_ref authorizes a legacy route; public availability or a matching ID alone does not create one.
• Canonical Product requires at least one format_options entry. Retain partially mapped products with mapped options and sanitized FORMAT_PROJECTION_FAILED entries; omit wholly unmappable products from the canonical list while retaining the non-fatal error in portable errors[] and SDK diagnostics. Never emit format_options: [] for a mapped canonical product.

Cross-language golden parity

Pin validation to the exact inputs, outputs, diagnostics, and transition behavior shipped in TypeScript RC3—not merely equivalent high-level behavior. The fixture is currently repository-local rather than a genuinely shared fixture package, so Python must vendor a versioned copy of the RC3 golden corpus until a shared package exists.

RC3 reference corpus:

• test/lib/v2-projection-fixtures
• test/lib/v1-to-v2-projection.test.js
• test/lib/catalog-unique-id.test.js
• test/lib/creative-format-projection.test.js
• test/lib/projection-catalog-adapters.test.js
• test/canonical-creatives-mcp-server-e2e.test.js

The stable migrated option-ID algorithm is normative:

identity = compact JSON([agent_url, id, width_or_null, height_or_null, duration_ms_or_null])
format_option_id = "migrated_" + HMAC-SHA256(key=b"", message=UTF8(identity)).hex()[0:32]

The complete legacy tuple and field order are part of the contract. Tests must assert exact IDs and stability under seller-array reordering.

Compatibility and release work

• Add inbound legacy_format_converter support for seller-owned formats and a separate canonical-to-legacy resolver for persisted canonical custom formats.
• Include a migration guide with canonical replacements and explicit legacy escape hatches.
• Audit examples and all root/alias re-exports so old shapes are not silently retained by convenience imports.
• Add transition tests for discovery → selection → serialization → create/update/sync → async/callback/webhook response.

Acceptance criteria

Primary model boundary

• A normal Python client/server integration completes the creative lifecycle without importing or handling agent_url, format_id, or format_ids.
• Recursive model_json_schema() tests prove those legacy fields are absent from every primary model.
• Recursive model_dump()/JSON tests prove primary models cannot emit those legacy fields.
• Root imports and all generic helpers expose the canonical surfaces described above; only explicit Legacy*/raw paths expose legacy identity.

Projection precedence and safety

• Resolve exact owner + ID catalog identity first.
• If exact lookup misses, allow a bare-ID fallback only when that ID has exactly one meaning in the bundled AAO catalog and the supplied owner is a valid public HTTPS owner.
• Preserve the complete original legacy tuple for same-process legacy delivery; do not rewrite it to the AAO owner.
• An explicit custom converter overrides compatibility inference, including intentional AAO-slug reuse.
• Reject ambiguous/colliding IDs, unsafe or invalid owners, invalid parameters, catalog conflicts, and contradictory dimensions/duration.
• Never reverse-guess after a process boundary. Persisted canonical selections require rediscovery/readback or an explicit durable canonical-to-legacy resolver backed by adopter storage.
• Preserve exact owner-sensitive v1_format_ref routes, including dimensional discriminators, for legacy delivery.

Interoperability and fixtures

• Legacy AdCP 3.0/3.1 peers interoperate through deterministic adapters or receive actionable projection errors.
• Seller-specific custom formats have tested bidirectional conversion hooks.
• Python vendors and passes the exact TypeScript RC3 golden inputs/outputs, including all 16 observed Vox, Triton, and OpenAds refs; historical aliases; unique bare-ID and collision cases; unsafe owners; contradictory parameters; original-tuple round trips; persistence boundaries; and all-unmappable discovery.
• Migrated option IDs exactly match the normative empty-key HMAC algorithm above.
• Public documentation clearly distinguishes Python SDK 7.0.0 from the negotiated AdCP protocol version.

References

• TypeScript canonical boundary and reference implementation: feat: enforce canonical creative SDK boundaries adcp-client#2391
• TypeScript reference release: @adcp/sdk@13.0.0-rc.3
• Existing Python projection layer: feat(canonical-formats): Pythonic v1↔v2 projection layer — parallel to adcp-client #1815 #741
• Existing Python canonical compatibility helpers: Add canonical creative format compatibility helpers #885
• Authoritative catalog aliases: fix(creative): publish deployed legacy format aliases adcp#6028
• AAO deployed-format catalog gaps: fix: publish canonical mappings for deployed AAO legacy format IDs adcp#6025

Cross-SDK tracking

• TypeScript: feat: enforce canonical creative SDK boundaries adcp-client#2391
• Python: feat: make canonical creatives the primary SDK contract #972
• Go: feat: make canonical creatives the primary SDK contract adcp-go#425
• Java: feat: make canonical creatives the primary SDK contract adcp-sdk-java#35

[bokelley]

Triage

Classification: Feature request (major, breaking)
Bucket(s): client, handlers (no matching repo labels found — flagging the gap)
Status: ready-for-human
Milestone: omitted (epic-shaped; no target version named in issue)

What the experts said:

• ad-tech-protocol-expert: Two blockers — (1) format_option_refs wire semantics on the buy side are unspecified in anything cited; feat(canonical-formats): Pythonic v1↔v2 projection layer — parallel to adcp-client #1815 #741 and Add canonical creative format compatibility helpers #885 cover seller-side projection only. (2) Python work must gate on TypeScript #2391 RC closing the cross-language fixture contract before Python can implement without diverging. Rename of FormatId({agent_url, id}) is a semver-major event that cannot ship as a minor under the current aliases.py import-layering contract.
• adtech-product-expert: Direction is correct — the SDK already treats {agent_url, id} as internal plumbing. Blocker: Python RC validation is hollow without a frozen cross-language fixture set ratified against TS, Go, and Java simultaneously. Concern: the scope (six handler methods, new converter hook, three-version capability matrix, async/webhook normalization, RC cycle) is at minimum four to five PRs — needs explicit task breakdown before work starts.
• dx-expert: Blocker — shipping all handler signature changes in one major bump gives adopters zero runtime warning in 3.x; the v2.5→v3 transition used AdapterPair shims with DeprecationWarning first, then hardened at 4.0; the same pattern should apply here. Concern — Legacy* naming collides with existing V1Canonical* convention in aliases.py; AgentUrl* would be self-documenting and conflict-free. Three migration guide gaps: AdapterPair/is_legacy_shape bridge compat, example updates (hello_seller_creative.py uses the old shape directly), and ~30 aliases.py cross-module aliases that silently re-export the wrong type after a rename.

My take: Experts converge on direction but surface two hard blockers and a structural concern. This is a semver-major, epic-shaped change that needs the TypeScript reference (#2391) to reach RC before Python implementation can begin, a phased rollout strategy (3.x shims → 4.0 hardening) rather than a single big-bang break, and an explicit task breakdown before any PRs are opened. Recommend @bokelley convert this to an epic with a task list once TS #2391 reaches RC.

Suggested task structure (not authoritative — human owns decomposition):

• Gate item: TS #2391 RC + frozen cross-language fixture contract
• Gate item: spec PR defining format_option_refs wire semantics on buy-side creative manifests
• Task 1: AgentUrl* shim layer in 3.x minor with DeprecationWarning across all public types
• Task 2: Capability matrix implementation (3.0 adapters, 3.1 feature-flag gate, 3.2+ enforcement)
• Task 3: Handler signature updates + legacy_format_converter / canonical-to-legacy resolver
• Task 4: Cross-language fixture integration + RC validation
• Task 5: Migration guide + example updates + aliases.py audit

---

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

---

Generated by Claude Code

[bokelley]

Implementation clarification from the TypeScript RC work:

1. Canonical publisher discovery and legacy projection are distinct. Snap's 11 canonical declarations are public, without authentication, at https://creative.adcontextprotocol.org/translated/snap/adagents.json; https://snapchat.com/.well-known/adagents.json currently returns 404, so publisher_domain: "snapchat.com" discovery must fall back to that community mirror and report source: "aao_mirror".
2. Do not copy those declarations into the legacy mapping registry or infer aliases by matching IDs. The current Snap mirror entries are canonical_formats_only: true and carry no v1_format_ref; they therefore do not authorize any {agent_url, id} legacy pairing. Seller/community catalogs participate in legacy projection only through an exact, owner-sensitive v1_format_ref (including dimensional discriminators). Public availability alone is insufficient.
3. Keep network resolution outside the pure projector. Feed it validated, cached catalog snapshots in precedence order (publisher → approved community mirror → agent-derived/configured), then use the custom converter only for genuinely unpublished semantics.
4. Canonical Product requires at least one format_options entry. For partial projection, retain the product with mapped options and add sanitized FORMAT_PROJECTION_FAILED entries. If no option maps, omit the product from the canonical list and retain the non-fatal error in the standard errors[]; never emit format_options: []. errors[] is the portable multi-hop surface.
5. Persisted canonical selections cannot be reverse-guessed from format_kind + params. Same-process implementations may use bounded private route caches keyed by account + product/publisher option identity. Across restarts or package-only update/sync flows, require re-discovery/readback or an explicit canonical-to-legacy resolver backed by adopter storage.

Please mirror these rules and the shared transition fixtures from adcontextprotocol/adcp-client#2391.

[bokelley]

Triage

Classification: Feature request (major, breaking)
Bucket(s): client, handlers
Status: ready-for-human
Milestone: omitted (epic-shaped)

What the expert said (re: new rules):

• ad-tech-protocol-expert: The 5 rules add useful scaffolding but don't resolve all prior blockers. Rule 4 specifies seller-side projection output semantics — buy-side format_option_refs wire encoding (how a buyer serializes them into OpenRTB or equivalent) is still unspecified. Three new schema gaps surface: FORMAT_PROJECTION_FAILED entry schema is undefined; Rule 2 requires "dimensional discriminators" for v1_format_ref exact-match but doesn't enumerate them; Rule 3's three-tier cascade leaves same-ID collision resolution and what "approved" community mirror means operationally both open.

What changes with these rules: The TS gate is partially lifted — discovery plumbing, three-tier resolver, catalog snapshot ingestion, and source: "aao_mirror" tagging can begin without waiting for the RC to close. Fixture-locked test assertions still need the finalized cross-language fixtures from adcontextprotocol/adcp-client#2391.

Two clarifications still needed before full task decomposition:

1. Buy-side format_option_refs wire encoding — likely warrants a sub-issue referencing the TS RC OpenRTB extension point.
2. Dimensional discriminators for v1_format_ref exact-match (Rule 2) — without them the legacy-projection gate predicate cannot be written and the canonical_formats_only: true guard cannot be correctly enforced.

My take: The new rules meaningfully enrich the implementation brief and partially unlock scaffolding work. The issue remains epic-shaped with two hard open questions; recommend filing the two sub-issues above before decomposing into implementation tasks.

---

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

---

Generated by Claude Code

[bokelley]

Implementation update: the authoritative catalog aliases are now in adcontextprotocol/adcp#6028, and the reference TypeScript behavior is in adcontextprotocol/adcp-client#2391 (commit 63be3dde2). Cross-SDK parity should include more than kind lookup: extract unambiguous fixed width/height/duration from catalog renders/asset requirements; use AdCP URL canonicalization while preserving path/query scope; allow validated inline discriminators only for parameterized templates; and emit FORMAT_PROJECTION_FAILED with distinct invalid-parameter vs catalog-conflict reasons for partial, nonpositive, fractional, ranged/ambiguous, or contradictory values.

[bokelley]

Triage

Classification: Feature request (major, breaking)
Bucket(s): client, handlers
Status: ready-for-human
Milestone: omitted (epic-shaped)

What the expert said (re: adcp#6028 + TS commit 63be3dde2):

• ad-tech-protocol-expert: adcp#6028 aliases partially resolve the discriminator blocker — kind-lookup advances, but the width/height/duration variant predicate is still missing from the alias entries. "Inline discriminators only for parameterized templates" partially resolves the gate condition but requires a machine-readable template/concrete taxonomy the catalog doesn't yet expose. "Extract unambiguous fixed dimensions from catalog renders/asset requirements" adds new scope — no current code parses renders[] or asset requirements for dimensional values; this is net-new implementation work. FORMAT_PROJECTION_FAILED's ErrorCode exists but the five sub-reason categories still lack a formal details object schema — partially resolves. Buy-side format_option_refs OpenRTB wire encoding does not resolve — still entirely unaddressed.

My take: The adcp#6028 reference and TS commit 63be3dde2 enrich the brief and partially advance the dimensional-discriminator blocker, but both prior blockers remain open. A new scope item surfaces: dimension extraction from catalog renders. The issue is still epic-shaped; recommend @bokelley confirm whether adcp#6028 alias entries enumerate valid parameter ranges (not just canonical kind names), and file a sub-issue for the buy-side OpenRTB mapping.

Two open questions remain:

1. Do adcp#6028 alias entries enumerate valid parameter ranges for dimensional variants, or only canonical kind names?
2. Buy-side format_option_refs wire encoding in OpenRTB — still unspecified; warrants a dedicated sub-issue referencing the TS RC extension point.

---

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

---

Generated by Claude Code