[bokelley]

Closes #8960

What changes

image_carousel gains an optional cta_values parameter that governs each card's cta. It has the same type as cta_values on native_in_feed and image, and carries "x-added-in": "3.3.0".

• When it is declared, every card's cta MUST be one of the listed values. A seller refuses any other value with CREATIVE_VALUE_NOT_ALLOWED, with error.field pointing at that card's cta.
• When it is absent, a card's cta takes free text and is not refused as CREATIVE_VALUE_NOT_ALLOWED.

This is additive on an open params object, so it is a minor, like card_image_sizes in #8937. Before this change, a carousel option could carry cta_values only as an undeclared extra parameter.

Files

• static/schemas/source/formats/canonical/image_carousel.json: the new cta_values property, using the definition proposed in the issue.
• static/schemas/source/core/assets/card-asset.json: the cta description now names image_carousel's cta_values as the governing set. It also states the refusal code, the error.field target and the free-text default.
• docs/creative/channels/carousels.mdx: the declaration example shows cta_values, the manifest example shows per-card cta, and a new "Card call to action" section says how cta_values governs each card's cta.
• docs/reference/whats-new-in-3-3.mdx and .changeset/image-carousel-cta-values.md: the release-doc entry and the changeset (minor).
• tests/x-added-in-3-3-sweep.test.cjs: registers the new property.

Compliance step: added

New optional scenario media_buy_seller/declared_carousel_cta_values (introduced_in: "3.3", gated on creative.has_creative_library). It mirrors declared_format_option_acceptance: the runner seeds a product whose image_carousel option declares cta_values: [SHOP_NOW, LEARN_MORE], and the buyer syncs a three-card creative with format_option_ref.

1. reject_card_cta_not_in_enum: cards one and two carry SHOP_NOW, and card three carries EXPLORE_MORE. The step expects CREATIVE_VALUE_NOT_ALLOWED, with errors[0].field matching cards\[2\]\.cta$.
2. accept_card_cta_in_enum: the same creative, with card three's cta set to LEARN_MORE, is accepted.

The scenario is not added to media_buy_seller's requires_scenarios. If it were required, every seller with a creative library would need to accept image_carousel before the RC. It runs wherever the seller's declared scope selects it, the same way creative/native_in_feed runs. Say so if you'd rather make it required.

Training agent

The training agent had no per-card checks for carousels. server/src/training-agent/task-handlers.ts now generalises the native_in_feed declaration resolution:

• formatOptionDeclarationGroups(formatKind, …) resolves the declaration in this order: format_option_ref, then assigned packages, then the agent's own capability.
• declaredFormatOptionError builds the error.

native_in_feed keeps its behaviour, and imageCarouselValidationError reuses both helpers. A card cta outside a declared cta_values returns CREATIVE_VALUE_NOT_ALLOWED at creatives[i].assets.cards[n].cta, with details.allowed_values. The agent declares no carousel capability params, so a carousel that no option governs stays unconstrained.

server/tests/unit/training-agent-image-carousel-cta-values.test.ts covers five cases:

• a refusal at the offending card;
• the accepted control;
• cards that omit cta;
• free text under an option without cta_values;
• free text with no governing declaration.

Overlap with #8949

#8949 (open) also edits the card-asset.json cta description, and it renames details.allowed_values to accepted_values on the line that now lives in the shared declaredFormatOptionError. Whichever PR merges second needs a small rebase. The wording here already covers what #8949 adds to card-asset cta.

Verification

VERIFICATION_PLACEHOLDER

🤖 Generated with Claude Code

[aao-secretariat]

Ladon verdict: Escalate to human review

Escalate — gated schema paths require human/CODEOWNERS approval.

This PR loosens the media_buy.audience_targeting capability contract (#8936): get-adcp-capabilities-response.json replaces an unconditional required: [supported_identifier_types, minimum_audience_size] with an if/then conditional. The reviewer verified the schema change across all four cases, confirmed docs↔schema coherence across 7 doc files, found the minor changeset correct for a loosening (precedent #8024/#8057), and surfaced no blocking or Medium findings. The change itself looks clean.

However, this PR modifies gated files under static/schemas/source/**:

• static/schemas/source/media-buy/sync-audiences-request.json
• static/schemas/source/protocol/get-adcp-capabilities-response.json

gated_paths is true and review_decision is REVIEW_REQUIRED (not APPROVED), so the hard approval gate (decision rule row 2) is not satisfied. Per policy this cannot auto-approve — a human/CODEOWNERS review is required to clear the gate. Once review_decision is APPROVED, a clean diff like this may fall through to approve.

Escalation reasons

• Modifies gated path static/schemas/source/protocol/get-adcp-capabilities-response.json — human/CODEOWNERS approval required (review_decision: REVIEW_REQUIRED).
• Modifies gated path static/schemas/source/media-buy/sync-audiences-request.json — human/CODEOWNERS approval required.

Why human review

• Modifies gated path static/schemas/source/protocol/get-adcp-capabilities-response.json — human/CODEOWNERS approval required (review_decision: REVIEW_REQUIRED, not APPROVED)
• Modifies gated path static/schemas/source/media-buy/sync-audiences-request.json — human/CODEOWNERS approval required
• This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/media-buy/sync-audiences-request.json (modified) matches static/schemas/source/**; static/schemas/source/protocol/get-adcp-capabilities-response.json (modified) matches static/schemas/source/**) and the current GitHub review decision is 'REVIEW_REQUIRED', not APPROVED. This is a hard gate enforced in code — Ladon cannot auto-approve until a human/CODEOWNERS approval is recorded, regardless of how clean the diff is.