fix(get_products): coerce string brand to BrandReference per AdCP v3 shorthand (4.3 gap)

[ChrisHuie]

Gap

Storyboard runner sends brand: "https://test.example" (string shorthand
form). Our _get_products_impl expects BrandReference (dict with
domain key). AdCP v3 accepts both forms — string is shorthand that
must be coerced server-side to BrandReference(domain=<string>).

Currently the string form fails Pydantic validation at the boundary.
Blocks the storyboard's primary brand-discovery flow.

Documented at #1247 gap #2 (storyboard compliance gap analysis).

Why it matters

• Spec compliance: AdCP v3 explicitly allows both shorthand and full
  reference forms
• Blocks storyboard from reaching downstream get_products scenarios

Contract for "done"

• _get_products_impl (or its boundary input model) coerces a
  string brand into BrandReference(domain=brand_string) before
  validation
• Dict form {"domain": "..."} continues to work unchanged
• Behavioral test exercises both forms produce identical downstream
  output
• Storyboard's brand-discovery scenarios pass against this code path

Out of scope

• Brand-resolution semantics (this is purely about shape coercion)
• A2A or REST transports (only MCP is in storyboard scope)

[mkostromin-sigma]

Taking this per Chris — URL normalize in to_brand_reference + tests for https://… shorthand. Blocked on #1512 for full storyboard discover phase.

[mkostromin-sigma]

Issue relationships (tracked for Monday work)

Parent: #1247 — AdCP storyboard compliance roadmap (gap #2)

Blocked by: #1512 — adcp_version / adcp_major_version MCP negotiation (Nicolas). Needed for full storyboard discover phase before brand-discovery scenarios are gradable end-to-end. Code fix here is independent; storyboard E2E verification waits on #1512.

Related (do not duplicate):

• feat: accept adcp_major_version on get_products + sync_accounts + other MCP tools (#1247 gap #1) #1308 — superseded by fix: MCP tools reject AdCP adcp_version/adcp_major_version negotiation fields — agent uncallable by official AdCP SDK clients #1512 for gap Welcome to salesagent Discussions! #1 (same root cause, different fix approach)
• feat(property-list): honest-declaration reject, Kevel siteId compilation, and faithful intersection (PR 2 after error-emission) #1389 / feat: wire buying_mode and refine through get_products (#1272)(PR 3 after error-emission) #1274 — Chris: full property_list + buying_mode/refine implementation (separate gaps feat: AI-Driven Product & Creative Format Management System #5–7)
• fix: AdCP 3.1 creative sync compliance — Changes 1-5 + 8 + brand test… #1482 — brand string normalization on creative sync path (not get_products; separate scope)

Assignee: @mkostromin-sigma — confirmed with Chris 2026-07-02.

[ChrisHuie]

Grounding + verified implementation findings

Analysis to ground the fix, from the pinned spec (adcp==5.7.0 → AdCP 3.1.0-beta.3) and current main (read + execution). Two things up front: the spec premise in the description needs correcting, and the coercion already exists in the codebase — in five places, one of which already does the right thing.

1. Spec: v3 has no string shorthand for brand

brand is object-only in the spec, at 3.1.0-beta.3 and at 3.0.1 (the pin when this was filed):

• core/brand-ref.json: "type": "object", "required": ["domain"], "additionalProperties": false; domain is a bare lowercase hostname (^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$). No oneOf: [string, object].
• media-buy/get-products-request.json: brand is a plain $ref to brand-ref.json — no string arm at the request level either.
• reference/migration/brand-identity.mdx: the string form was v2.5's brand_manifest (a URL); v3 replaced it with the brand object whose domain is a bare hostname.

Consequence: BrandReference(domain="https://test.example") (the literal in the "done" checklist) raises ValidationError — the scheme/colon/slashes fail the domain pattern. Accepting a string is a seller-side leniency (Postel), not a spec shorthand; the code comment # AdCP v3 allows "acme.com" is inaccurate and should say so. Normalize at the seller boundary; keep the AdCP type strict.

2. Code: the coercion already exists — five ways, one correct

Site	Behavior	URL	Port	Bare domain
to_brand_reference str branch (src/core/schema_helpers.py)	BrandReference(domain=brand) raw	✗	✗	✓
get_products wrapper inline (src/core/tools/products.py)	raw (duplicate)	✗	✗	✓
create_media_buy wrapper inline (src/core/tools/media_buy_create.py)	raw (duplicate)	✗	✗	✓
_brand_str_to_ref (src/core/helpers/creative_helpers.py)	strip scheme/path + lowercase	✓	✗	✓
_translate_brand_manifest v2.5 (src/core/request_compat.py)	urlparse hostname	✓	✓	✗

get_products and create_media_buy route strings through the raw variant, which throws on any URL (including this issue's https://test.example). Meanwhile _brand_str_to_ref already strips scheme/path and lowercases — "https://advertiser.example.com/brand" → domain="advertiser.example.com", exercised green in tests/unit/test_creative_agent_registry.py. build_creative uses _brand_str_to_ref for strings but to_brand_reference for dicts, so the correct behavior already lives in the tree; the two other tools just call the wrong helper.

The to_brand_reference URL-normalize direction is the right instinct — with a second-order caveat: _brand_str_to_ref uses regex/split, not urlparse, so it keeps the port ("https://acme.com:8443/x" → "acme.com:8443" → ValidationError), and that case is untested. The complete extractor is urlparse().hostname + a bare-domain fallback (urlparse returns hostname=None for a scheme-less "acme.com") + .lower() — a superset of both existing URL-aware helpers. A urlparse-only fix regresses the bare-domain case.

Error path (verified): a bad brand already surfaces as 400 VALIDATION_ERROR / correctable (pydantic ValidationError subclasses ValueError, and normalize_to_adcp_error maps it), but with no recovery suggestion and the raw pydantic dump as the message. Raising a typed AdCPValidationError(..., suggestion=...) from the shared helper produces the two-layer envelope with recovery — the coerce_creative_filters precedent in the same file.

FastMCP boundary (verified): the brand: BrandReference | str param means a string (bare or URL) reaches the handler as str, while a malformed dict fails at the TypeAdapter before the handler runs. So the string path is the one to fix for MCP; the dict-branch typed error only affects A2A/REST.

3. Revised contract for "done"

• One shared URL→hostname extractor (urlparse().hostname + bare-domain fallback + lowercase — strips scheme/path/query/fragment/port). to_brand_reference delegates to it; _brand_str_to_ref and the v2.5 _translate_brand_manifest string-path collapse onto it (single source).
• Remove the raw inline coercion in the get_products (and create_media_buy) wrappers; correct the "AdCP v3 allows" comments to describe a seller-side leniency.
• Un-normalizable input (IPv6 literal, empty, non-domain) → typed AdCPValidationError with a suggestion, asserted on the wire envelope (assert_envelope_shape(..., "VALIDATION_ERROR", recovery="correctable") per tests/CLAUDE.md), not a reconstructed exception.
• Parametrized behavioral test: "acme.com", "https://acme.com", "https://acme.com/.well-known/brand.json", "HTTPS://ACME.COM:8443/x", {"domain":"acme.com"}, and a BrandReference all produce identical downstream output; include the port case; keep the test_creative_agent_registry.py URL test green as the consolidation regression guard.

4. Scope + sequencing notes

• create_media_buy has the identical raw coercion, and brand is required there (optional on get_products) — so a URL-string brand failing is higher-stakes. Fold it into the same consolidation or file a sibling; fixing one copy while leaving the other reintroduces the divergence.
• End-to-end conformance-runner verification is blocked on the version-negotiation fix (fix: MCP tools reject AdCP adcp_version/adcp_major_version negotiation fields — agent uncallable by official AdCP SDK clients #1512): the runner can't pass capability discovery, so the get_products step isn't reached. Verify here with the behavioral test above.
• Adjacent, out of scope: buying_mode passthrough (feat: AdCP storyboard compliance — gap analysis and roadmap #1247 gap 5 — the local GetProductsRequest makes buying_mode optional, so it's silently dropped today) and "brand required when catalog is provided" (per the migration doc).
• Suggest running ./run_all_tests.sh ci (not just make quality, which is unit-only/offline) since this touches a shared helper across transports.

[mkostromin-sigma]

Implemented in #1537 — spin-off from #1247 gap #2. Root cause: partial coercion existed but https://test.example failed BrandReference domain pattern; now normalized via brand_shorthand_to_domain() in to_brand_reference().

[mkostromin-sigma]

Implementation: #1537 — CI green, awaiting review.