[v13 rc.11] Native SalesPlatform drops package format_ids compatibility metadata

[bokelley]

Summary

@adcp/sdk@13.0.0-rc.11 cannot preserve the deprecated Package.format_ids echo contract when a DecisioningPlatform implements the native media-buy methods.

The runtime canonicalizes a 3.0 create_media_buy request before calling SalesPlatform.createMediaBuy, then validates the platform result as canonical before projecting it back to the negotiated legacy wire. This creates two related failures:

1. A platform result containing both stable format_option_refs and the original format_ids is rejected/normalized before the legacy projector can preserve the original IDs.
2. serverOptions.legacyHandlers.mediaBuy.{createMediaBuy,updateMediaBuy,getMediaBuys} cannot provide an explicit raw compatibility facade because those handlers are shadowed by the native platform methods.

The package schema says sellers SHOULD echo format_ids whenever supplied, including dual-emission cases where format_option_refs wins selector precedence.

Reproduction

Configure a DecisioningPlatform sales tenant plus legacyHandlers.mediaBuy.createMediaBuy, then send a negotiated 3.0 request with:

{
  "adcp_version": "3.0",
  "packages": [{
    "product_id": "legacy_product",
    "pricing_option_id": "fixed_cpm",
    "budget": 10000,
    "format_ids": [{
      "agent_url": "https://creative.adcontextprotocol.org/",
      "id": "display_300x250_image",
      "width": 300,
      "height": 250
    }]
  }]
}

Observed platform input for a recognized legacy ID contains only a temporary migrated_* format_option_ref. Returning the original format_ids alongside the platform's stable canonical ref does not preserve it through the native platform boundary. The configured legacy handler is not called; rc.11 logs:

opts.legacyHandlers.mediaBuy.{createMediaBuy, updateMediaBuy, getMediaBuys}
are shadowed by platform-derived handlers

For a product combining one canonically mapped legacy ID and one truly legacy-only ID, canonical projection retains only the mapped option. The native response projector therefore cannot reconstruct the full original format_ids selection.

Expected

Provide a supported compatibility channel for native platform methods to retain exact legacy selector metadata across canonical request handling and legacy response projection. Either:

• preserve the original package format_ids as hidden/request metadata and merge them on the negotiated legacy response;
• allow raw legacy media-buy handlers to take precedence for 3.0 requests; or
• expose an explicit platform response sidecar that the canonical validator ignores and the legacy projector consumes.

The canonical platform result should continue to use stable format_option_refs; temporary migrated_* aliases must not become durable state.

Downstream

adcontextprotocol/adcp#6307 resolves temporary aliases into stable canonical refs, retains original legacy tuples only in compatibility state, and strips legacy metadata at the native canonical platform boundary. Fully mapped selectors round-trip through configured routes, but mixed mapped + truly legacy-only selector echo requires an SDK fix.

[bokelley]

Triage

Classification: Bug
Bucket(s): library
Status: ready-for-human

What the experts said:

• code-reviewer: Bug confirmed at two sites — creative-delivery.ts:878 unconditionally deletes format_ids in canonical wire mode, silently dropping mixed-selector packages before the platform sees the request; from-platform.ts:3595 mergeHandlers gives platform-derived handlers unconditional precedence, eliminating the legacyHandlers.mediaBuy escape hatch entirely. Option B is architecturally unsound (breaks the canonical platform boundary contract). Option C (response sidecar) is correct for the echo contract. HITL paths have a structural WeakMap gap that would affect any Option-A variant.
• ad-tech-protocol-expert: Agrees — Option C is sound for the response-echo contract; Option A is structurally problematic (WeakMap refs don't survive HITL task-registry handoffs); flags that the mixed-selector subcase may be conditionally blocked on adcp#6307 for the spec's normative "fully-mapped selector" definition, while the pure-legacy case is independently fixable today.

My take: Both experts converge on Option C — an optional _legacy_format_ids_sidecar field on SalesPlatform.createMediaBuy/updateMediaBuy return types, ignored by the canonical validator and consumed by the legacy projector — and reject Option B. They disagree on whether the mixed-selector echo fix is independently deliverable or requires adcp#6307 to land first. The new SalesPlatform surface and that spec-dependency question need a maintainer call before implementation. @bokelley — should the mixed-selector fix land before or after adcp#6307, and is Option C the intended approach?

When authorized, implementation scope:

• src/lib/v2/projection/creative-delivery.ts:846–878 — gate delete next.format_ids on a full-mapping check; emit diagnostic (matching the projectV1ProductToV2 pattern) for unmapped entries in mixed-selector packages
• src/lib/server/decisioning/runtime/from-platform.ts — add optional sidecar field to SalesPlatform response types; consume in the legacy response projector
• Add test coverage for mixed-selector path in projectPackageSelectors (currently none)
• Changeset required (patch bump)

---

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code