feat: make canonical creatives the primary SDK contract

[bokelley]

Context

The TypeScript SDK is making canonical creatives the contract of its next major release in adcontextprotocol/adcp-client#2391. Adopting the modern SDK should 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.

The Java SDK should establish the same boundary across its core, server, Spring Boot, Reactor, Mutiny, and Kotlin-facing modules so language/runtime choice does not preserve legacy creative identity in normal adopter code.

Required behavior

• Add canonical creative-bearing models and make them the default public types for products, packages, creatives, media-buy requests/responses, delivery responses, and server handler payloads.
• Move raw {agent_url, id} creative shapes behind explicit Legacy* model names and explicitly named legacy client/server methods or packages.
• Make primary discovery and write methods 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 a conspicuous legacy surface; hard-deprecate it for removal with AdCP 4.0.
• 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.
• Keep catalog lookup URL-sensitive, including explicit historical AAO aliases; never match an unrelated owner by ID alone.
• Add an inbound legacy-format converter for seller-owned formats and a separate canonical-to-legacy resolver for persisted canonical custom formats.
• Omit a wholly unmappable product from the primary canonical product list, retain partially mapped products, and surface a sanitized portable advisory plus SDK diagnostics; never guess or omit without an advisory.
• Fail before transport for ambiguous, incomplete, invalid, or canonical-only downgrades.
• Preserve canonicalization context across synchronous calls, CompletionStage, Reactor, Mutiny, polling, async completion, and webhooks without unbounded task-state retention.
• For server/Spring APIs, normalize legacy inbound requests before adopter handlers and project responses back to the caller's negotiated dialect.

Java-specific design notes

• Keep generated wire DTOs separate from canonical application models rather than exposing both legacy and canonical identity as peer fields on one normal DTO.
• Model canonical format declarations as a sealed hierarchy or equivalent discriminator-safe API.
• Use distinct functional interfaces for legacy→canonical conversion and canonical→legacy resolution.
• Expose a typed projection exception containing operation, affected creative/product, and reason; preserve it consistently across synchronous, Reactor, and Mutiny surfaces.
• Ensure Kotlin consumers see the same canonical nullability and sealed-type behavior.

Compatibility and release

• Treat this as a major Java SDK change and publish an RC before GA.
• Include a migration guide with canonical replacements and explicit legacy escape hatches.
• Add cross-language fixtures shared with the TypeScript, Python, and Go SDKs, covering known AAO formats, historical aliases, custom formats, persistence boundaries, and all-unmappable discovery.
• Add transition tests for discovery → selection → serialization → create/update/sync → async/webhook response across the supported async adapters.

Acceptance criteria

• A normal Java/Kotlin client or server integration can complete the creative lifecycle without handling agent_url, format_id, or format_ids in application code.
• Legacy AdCP 3.0/3.1 peers still interoperate through deterministic adapters or return actionable projection errors.
• Seller-specific custom formats have tested bidirectional conversion hooks.
• Core, server, Spring Boot, Reactor, Mutiny, and Kotlin modules expose consistent canonical semantics.
• Public documentation clearly distinguishes the SDK major version from the negotiated AdCP protocol version.
• RC validation uses the same cross-language transition fixture and expected diagnostics as feat: enforce canonical creative SDK boundaries adcp-client#2391.

References

• TypeScript canonical boundary: feat: enforce canonical creative SDK boundaries adcp-client#2391

• Python projection work: feat(canonical-formats): Pythonic v1↔v2 projection layer — parallel to adcp-client #1815 adcp-client-python#741

• Go projection work: feat(canonical-formats): Go v1↔v2 projection layer — parallel to adcp-client #1815 adcp-go#127

• AAO deployed-format catalog gaps: fix: publish canonical mappings for deployed AAO legacy format IDs adcp#6025

Cross-SDK tracking

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

[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]

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]

TypeScript reference behavior is now implemented in adcontextprotocol/adcp-client#2391:

• inbound legacy {agent_url, id} first uses exact owner+ID catalog identity;
• when the owner is wrong but the bare ID has exactly one bundled AAO meaning, it projects canonically and preserves the original tuple for same-client legacy delivery;
• duplicate IDs, contradictory dimensions/duration, invalid/HTTP/private owners fail closed;
• an adopter converter overrides the compatibility heuristic for intentional slug reuse;
• generated option IDs are stable across seller array reordering;
• process-boundary reverse delivery still requires a durable catalog adapter/resolver.

Production coverage includes all 16 observed Vox, Triton, and OpenAds refs, plus an end-to-end Vox getProducts → create/update/sync exact-tuple regression. Please mirror these precedence and safety semantics rather than doing an unrestricted bare-ID match.