get_products conversion to AdCP 3.1 drops collection_ref from installments #1895

What happens

When a seller's get_products response is converted for an AdCP 3.1 caller, each installment's collection_ref is dropped. Nothing takes its place. The drop happens at the 3.2 → 3.1 step of adcp.compat.versions.convert_payload, which the MCP tool caller runs on every response it returns to an older buyer. The loss is recorded as field_unavailable.

AdCP 3.1 has no collection_ref. Its installment names its parent collection with collection_id, which 3.1 describes as "Required when the product spans multiple collections". In 3.2 and later, collection_id is kept as the deprecated shorthand for one publisher namespace. So a 3.1 buyer of a product with several collections receives episodes that don't say which collection they belong to.

Reproduction (adcp 10.0.0b13)

import adcp
from adcp.compat.versions import convert_payload

installment = {
    "installment_id": "ep12",
    "collection_ref": {"publisher_domain": "podcasts.example", "collection_id": "show_b"},
    "name": "Episode 12",
}
product = {
    "product_id": "network_midrolls",
    "collections": [{"publisher_domain": "podcasts.example", "collection_ids": ["show_a", "show_b"]}],
    "installments": [installment],
}
converted = convert_payload(
    "get_products",
    {"products": [product]},
    direction="sync",
    source_version="3.3-beta.5",
    target_version="3.1",
)
print(adcp.__version__)                                   # 10.0.0b13
print(converted.payload["products"][0]["installments"])  # [{'installment_id': 'ep12', 'name': 'Episode 12'}]
print(converted.metadata())
# [{'pointer': '/products/0/installments/0/collection_ref', 'source_version': '3.2',
#   'target_version': '3.1', 'reason': 'field_unavailable'}]

Expected

When an installment has collection_ref and no collection_id, the 3.2 → 3.1 step sets collection_id to collection_ref.collection_id before dropping collection_ref, at least when every collection of the enclosing product shares one publisher_domain, where the shorthand is unambiguous. Across several publishers the mapping could be ambiguous; recording that as a loss, as today, seems right there.

Workaround in the meantime

Our sales agent publishes collection_id beside collection_ref on each installment of a product whose collections share one publisher, so the field survives the conversion. On a product that spans several publishers, installments stay unmapped for 3.1 buyers.