feat(media-buy): add compact AdCP 3.2 lifecycle

[bokelley]

What changed

• add the compact AdCP 3.2 lifecycle: list_products, request_proposals, refine_proposals, decline_proposals, buy_products, accept_proposal, and control_media_buy
• make accept_proposal the single commitment boundary for creating, amending, or canceling a MediaBuy from a committed proposal
• support direct product purchase through buy_products and operational controls through control_media_buy
• route commercial changes through refine_proposals(accepted_proposal_id) followed by accept_proposal; accepted snapshots remain immutable
• keep creatives on the separate sync_creatives path: the new purchase/control inputs do not accept inline creatives, legacy creative shapes, BrandRef payloads, or transitive provenance graphs
• keep get_products, create_media_buy, and update_media_buy as 3.x compatibility facades, with machine-readable fallback metadata for SDK adapters
• use canonical compact account, brand, product, proposal, targeting, optimization, measurement, and reporting views
• add durable wholesale product-feed webhook/mirror semantics; list_products is the synchronous bootstrap and repair read
• incorporate the reusable opportunity lifecycle from feat(media-buy): add opportunity and proposal decline flow #5523 and keep targeting-aware product-filter work composable with feat(media-buy): add targeting-aware product discovery #6203

Lifecycle boundaries

• list_products reads offers only and never creates proposals.
• request_proposals produces immutable committed snapshots; refine_proposals forks new snapshots.
• buy_products commits listed products without a proposal workflow.
• accept_proposal creates a buy or applies an accepted amendment/cancellation proposal.
• control_media_buy handles operational actions within the accepted envelope. Changes to product, flight, budget, targeting, billing/measurement, performance, or reporting terms require proposal refinement and acceptance.
• sync_creatives remains the only creative-management surface for this lifecycle.
• get_media_buys returns the accepted proposal and canonical routed actions so clients can recover the correct next step after restart.

Versioning and compatibility

This is additive in AdCP 3.2. Legacy tools remain supported throughout 3.x and map to the canonical lifecycle through declared fallback grades and operation families. Stateful calls replay only under their own canonical tool identity; exact retries converge, while reuse with different logical input conflicts.

The stricter removal of compatibility surfaces, inline creatives, and transitively inlined creative/provenance data remains 4.0 work.

Surface-area result

• full MCP projection: 71 tools, 142 schemas, 12.32 MiB
• production 3.2 profile: 66 tools, 132 schemas, 3.23 MiB structural projection
• the production profile excludes compliance-only and deprecated compatibility tools and strips presentation annotations without changing validation semantics
• hosts still select only their implemented protocol/capability subset; the profile is a clean catalog and validation source, not a recommendation to load all tools into one model context

Additional review fixes

• bind accepted proposal MediaBuy IDs and canonical available actions in commitment/recovery responses
• require the appropriate wholesale product payload view and prohibit it for non-product webhook events
• document PROPOSAL_UNAVAILABLE for committed offers without reserved inventory
• add countries and property_list offer attributes without turning discovery into delivery targeting
• publish compact task-specific async envelopes for proposal planning and re-underwriting
• support account IDs and natural-key accounts consistently in schemas and the training runtime

Validation

• independent code and protocol expert reviews: no merge blockers
• build and TypeScript no-emit: clean
• focused lifecycle/idempotency/runtime suites: 709/709
• composed schema validation: 344/344
• MCP schema projection/profile validation: 14/14
• schema registry, docs navigation, schema links/UTF-8, compliance generation, error-code drift, current storyboard matrix, and released 3.0 compatibility storyboard matrix: clean
• merged with current main and the latest remote PR branch; conflicts resolved

Human/CODEOWNERS approval is still required because this PR changes gated protocol schema paths.

[aao-secretariat]

Ladon verdict: Escalate to human review

Escalate — gated schema path change requires human/CODEOWNERS review, and this is a Breaking-class protocol change.

This PR classifies get_products as state-mutating and adds a required idempotency_key to the published request schema — an optional→required addition on a published wire surface, i.e. a Breaking-class change. It correctly carries a major changeset and schema↔docs coherence checks out (idempotency_key row: Yes, 16-255, matching pattern; manifest, examples, compliance fixtures, MCP/v5/v6 routes, and Addie tools all coherent). The idempotency.ts fencing and task-handlers recovery/natural-key reuse logic were reviewed and are sound.

Two escalation triggers apply and neither is satisfiable by the arbiter:

• Gated paths: static/schemas/source/manifest.schema.json and static/schemas/source/media-buy/get-products-request.json are under the hard approval gate (gated_paths: true), and review_decision is REVIEW_REQUIRED (not APPROVED). Decision-table row 2 forces escalate.
• Repo hard gate: a Breaking-class protocol change is never auto-approved — ratification is a human act — unless review_decision is APPROVED. It is not.

No critical/high findings were reported (a correct major changeset accompanies the breaking change, so no spec-drift/changeset finding). One Medium remains: the new per-session get_products mutex CONFLICTs concurrent pure reads.

Human/CODEOWNERS review of the gated schema files is required before this can merge.

Medium findings:

• server/src/training-agent/task-handlers.ts:3912 — get_products session mutex CONFLICTs concurrent pure reads

Medium findings

• server/src/training-agent/task-handlers.ts:3912 — get_products session mutex CONFLICTs concurrent pure reads

Why human review

• Modifies gated schema files static/schemas/source/manifest.schema.json and static/schemas/source/media-buy/get-products-request.json under the hard approval gate; review_decision is REVIEW_REQUIRED, not APPROVED — human/CODEOWNERS review required.
• Breaking-class protocol change (optional→required idempotency_key on published get_products request schema, get_products reclassified as state-mutating) — never auto-approved; ratification is a human act unless review_decision is APPROVED.
• Medium: server/src/training-agent/task-handlers.ts:3912 — get_products session mutex CONFLICTs concurrent pure reads.
• This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/manifest.schema.json (modified) matches static/schemas/source/**; static/schemas/source/media-buy/get-products-request.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.

[aao-secretariat]

Ladon verdict: Escalate to human review

Escalate — gated schema files require human/CODEOWNERS review; a Breaking-class protocol change is present.

Escalation reasons

• Gated path not satisfied: modifies static/schemas/source/manifest.schema.json and static/schemas/source/media-buy/get-products-request.json under the hard, non-overridable approval gate; review_decision is REVIEW_REQUIRED, not APPROVED. Human/CODEOWNERS approval is required before merge.
• Breaking-class protocol change (optional→required idempotency_key on the published get_products request schema; get_products reclassified as state-mutating) is never auto-approved — ratification is a human act unless review_decision is APPROVED.

Iteration note
The prior medium finding (get_products session mutex CONFLICTing concurrent pure reads at server/src/training-agent/task-handlers.ts:3912) is resolved: brief/wholesale now take the mutex only for a bounded (~1s, backoff+jitter) directive-consumption preflight, release before read-only work, and no longer write lastGetProductsContext. Directive consumption is threaded through readDirectives so exactly one of N parallel reads consumes a one-shot rejection. Four concurrency tests added. No new blocking or medium findings in the delta.

The escalation persists solely because the gated-path approval gate remains unsatisfied (REVIEW_REQUIRED) and the underlying change is Breaking-class — not because of any unresolved reviewer finding. The gate lifts the moment a human/CODEOWNERS approval is recorded.

Why human review

• Gated paths not satisfied: static/schemas/source/manifest.schema.json and static/schemas/source/media-buy/get-products-request.json are under the hard approval gate and review_decision is REVIEW_REQUIRED, not APPROVED — human/CODEOWNERS review required.
• Breaking-class protocol change (optional→required idempotency_key on published get_products request schema; get_products reclassified as state-mutating) is never auto-approved unless review_decision is APPROVED — human ratification required.
• This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/manifest.schema.json (modified) matches static/schemas/source/**; static/schemas/source/media-buy/get-products-request.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.

[aao-secretariat]

Ladon verdict: Escalate to human review

Escalate — hard approval gate unsatisfied plus breaking-class protocol change.

This PR modifies published protocol source under static/schemas/source/** (manifest.schema.json, media-buy/get-products-request.json), which is a deterministic hard approval gate: gated_paths: true and review_decision: REVIEW_REQUIRED (not APPROVED). Row 2 of the decision table fires — cannot auto-approve until a human/CODEOWNERS approval is recorded.

Independently, the reviewer confirms this delta reframes the get_products idempotency contract as a 4.0 major boundary: idempotency_key is in required[] with x-mutates-state:true, an optional→required flip on a published field that reclassifies get_products as state-mutating. That is a Breaking-class protocol change under the constitution and the repo's "Breaking-class changes are never auto-approved" hard gate — ratification is a human act, escalate unless review_decision is APPROVED. It is not.

Reviewer found no Critical/High/Medium correctness findings in the delta; schema↔docs coherence holds (security.mdx, specification.mdx, get_adcp_capabilities.mdx align on the 4.0 cut), oneOf/canonical coverage preserved, deploy wiring safe. The only finding is one low-severity legacy-wire projection note, which does not block on its own. But the two hard gates above are dispositive.

Escalation reasons

• Gated paths not satisfied: static/schemas/source/manifest.schema.json and static/schemas/source/media-buy/get-products-request.json are under the hard approval gate and review_decision is REVIEW_REQUIRED, not APPROVED — human/CODEOWNERS review required.
• Breaking-class protocol change: optional→required idempotency_key flip on published get_products request schema; get_products reclassified state-mutating. Never auto-approved unless review_decision is APPROVED — human ratification required.

Why human review

• Gated paths not satisfied: static/schemas/source/manifest.schema.json and static/schemas/source/media-buy/get-products-request.json are under the hard approval gate and review_decision is REVIEW_REQUIRED, not APPROVED — human/CODEOWNERS review required.
• Breaking-class protocol change: optional→required idempotency_key flip on the published get_products request schema, reclassifying get_products as state-mutating. Ratification is a human act — never auto-approved unless review_decision is APPROVED.
• This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/manifest.schema.json (modified) matches static/schemas/source/**; static/schemas/source/media-buy/get-products-request.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.

[aao-secretariat]

Ladon verdict: Escalate to human review

Escalate — hard approval gate not satisfied + Breaking-class protocol change requires human ratification.

Escalation reasons

• Gated paths not satisfied: static/schemas/source/manifest.schema.json and static/schemas/source/media-buy/get-products-request.json are under the repo's hard, non-overridable approval gate and review_decision is REVIEW_REQUIRED, not APPROVED. Human/CODEOWNERS review is required before merge (decision-table row 2).
• Breaking-class protocol change: an optional→required idempotency_key flip on the published get_products request schema, reclassifying get_products as state-mutating (x-mutates-state: true). Per repo governance, Breaking-class changes are never auto-approved even with a correct major changeset — ratification is a human act. Escalate unless review_decision is APPROVED.

Findings
No critical/high/medium code findings surfaced this run. The reviewer verified schema↔docs coherence (schema requires the key + x-mutates-state:true; get_products.mdx marks Required:Yes), a correct major changeset, no oneOf/additionalProperties regressions, and confirmed the session-mutex, hash-aware fenced idempotency claim/save/release, and durable-state flush paths are safe.

This is the same posture as the prior escalate decision: the diff is clean, but the gated path + Breaking-class governance gate hold until a human/CODEOWNERS approval is recorded. Once review_decision becomes APPROVED, this PR falls through to a normal approve.

Why human review

• Gated paths not satisfied: static/schemas/source/manifest.schema.json and static/schemas/source/media-buy/get-products-request.json are under the hard approval gate and review_decision is REVIEW_REQUIRED, not APPROVED — human/CODEOWNERS review required.
• Breaking-class protocol change: optional→required idempotency_key flip on the published get_products request schema, reclassifying get_products as state-mutating (x-mutates-state:true). Ratification is a human act — never auto-approved unless review_decision is APPROVED, even with a correct major changeset.
• This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/manifest.schema.json (modified) matches static/schemas/source/**; static/schemas/source/media-buy/get-products-request.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.

[bokelley]

Issue #6432 proposes behavioral compliance storyboards for list_products, request_proposals, refine_proposals, and decline_proposals — same surface as this PR. The four task pages were flipped to testable: false as an interim measure; folding the storyboards before merge would restore testable: true rather than shipping the gap into 3.2. If scope expansion would delay WG review, close the fold window here and the issue will resurface as a tracked follow-up on merge.

---

Generated by Claude Code

[bokelley]

All four findings addressed in commit 6c033bab4. Summary:

Finding 1 (blocker) — committed semantics + PROPOSAL_UNAVAILABLE

• proposal-status.json: Added normative sentence — a seller that did not reserve inventory MAY reject an unexpired committed proposal at create_media_buy via PROPOSAL_UNAVAILABLE; availability risk pre-execution is on the buyer absent a stated hold.
• error-code.json: Added PROPOSAL_UNAVAILABLE with correctable recovery guidance (call request_proposals for a fresh executable proposal; consider requesting a hold in the brief if inventory reservation is required). Compliance snippet regenerated.
• create_media_buy.mdx: Added paragraph explaining the no-hold rejection path and directing buyers to request a hold in the request_proposals brief.

Finding 2 (well-founded) — list_products scoping

• product-offer-filters.json: Added countries (ISO 3166-1 alpha-2 array) and property_list ($ref to property-list-ref.json). channels was already present.
• list-products-response.json: Overrode the $ref-inherited incomplete description — clarified it fires on result-count truncation at the page cap; time_budget has no meaning for a synchronous task and MUST NOT be used as a trigger condition.
• list-products-request.json: Added description to push_notification_config marking it a reserved dead surface for this sync task.

Finding 3 (blocker) — async at request_proposals / refine_proposals

• Created request-proposals-async-response-submitted.json and refine-proposals-async-response-submitted.json following the established per-task template (status: "submitted", task_id required, not constraint blocking result fields).
• async-response-data.json: Both schemas registered in the webhook union anyOf.
• request_proposals.mdx / refine_proposals.mdx: One-line MAY-async statement added to each.

Finding 4 (well-founded) — compliance coverage

• All four new task pages (list_products, request_proposals, refine_proposals, decline_proposals) flipped to testable: false.
• Tracking issue filed: compliance: add behavioral storyboards for the 3.2 compact product lifecycle #6432 covers the happy-path storyboard (list_products → request_proposals → create_media_buy), decline-terminality probe, expiry probe, and the no-hold rejection probe.

---

Generated by Claude Code

[bokelley]

@lukasz-pubx Thanks for the detailed review — the latest head (4deaa0917a) addresses the findings:

• Inventory hold restored: refine_proposals with action: "finalize" now MUST target a draft and creates a new immutable committed proposal with inventory reserved through expires_at, restoring the 3.1 meaning. accept_proposal consumes that exact held snapshot; expiry returns PROPOSAL_EXPIRED. Finalize batches are exclusive, atomic, and idempotently recoverable.
• Catalog scale: list_products remains a synchronous bootstrap/repair read, paired with the existing durable account-level product.* and wholesale_feed.bulk_change webhooks so buyers maintain a mirror without polling. The compact filters now include country and property-list scoping, and feed/pricing versions support conditional repair.
• Async planning: request_proposals and refine_proposals now explicitly support the shared status: "submitted" task envelope, polling, and push completion; both schemas and task docs describe it.
• Compliance disposition: the new pages are explicitly testable: false rather than claiming unimplemented coverage, and behavioral storyboard work is tracked in compliance: add behavioral storyboards for the 3.2 compact product lifecycle #6432. The PR adds schema/runtime lifecycle coverage for immutable revision, decline terminality, expiry, atomic finalization, crash recovery, and accept/amend/cancel paths.
• Union clarity: revision callers now send explicit action: "revise"; revise/finalize is a proper discriminated union for generated SDKs.

All inline review threads are resolved, both protocol and implementation re-reviews passed, and the full GitHub check set is green.

[lukasz-pubx]

Following up on my earlier review — re-reviewed at 4deaa0917. First: the redesign addresses my previous findings well. Restoring the reservation guarantee via draft → refine_proposals(action: "finalize") → accept_proposal gives the lifecycle exactly the "lock the deal" step real-world deals have, the digest-bound acceptance is a strong touch, the async arms (submitted/working/input-required across the proposal tasks) close the consultative-seller gap, and the wholesale feed webhook/mirror model with countries/property_list filters is an elegant answer to catalog scale. Thank you for engaging with the feedback so substantively.

I've now stress-tested the new lifecycle from the perspective of a multi-tenant sales agent — one agent representing many publishers, thousands of products, some generated on the fly. The model is clearly contemplated (the refine_proposals async text even names "complex multi-publisher revision or inventory hold requires upstream pricing queries or manual re-underwriting"), and cross-publisher proposals are arguably where this lifecycle shines. But four mechanisms that this topology depends on are underspecified, and each is a paragraph-sized fix now versus interop divergence later:

1. Hold duration is unpriced. accept_proposal states "An unexpired committed proposal cannot be rejected merely because its reserved inventory was sold elsewhere" — which makes an intermediary without upstream reservation APIs the underwriter of every hold window. The only pressure valve is that expires_at is seller-set with no floor: a 5-minute hold is conformant, which rescues the aggregator but guts the buyer value of committed. Is that intended? Ask: either state a normative expectation (or explicit non-expectation) for hold duration, or let sellers declare typical hold windows in capabilities so buyers can price the difference between a 10-minute and a 72-hour committed before finalizing.

2. Batch-finalize atomicity lacks refusal semantics. refine_proposals mandates "Sellers validate the complete batch before creating any holds; multi-proposal finalization is atomic." Legacy had MULTI_FINALIZE_UNSUPPORTED precisely for "the proposals route to two different ad servers with no 2PC" — the multi-publisher case verbatim — but the error catalog still scopes that code to the legacy get_products refine[]. Can a single batch return mixed finalized/unable results, or does atomicity forbid that? And which error code refuses a cross-ad-server atomic finalize on the new task? Ask: wire MULTI_FINALIZE_UNSUPPORTED (or a successor) to refine_proposals and state whether mixed outcomes are conformant.

3. On-the-fly products have no sanctioned route to direct purchase. buy_products requires feed_version, so a product generated per-brief is only transactable via the proposal path — which now mandates a hold at finalize. The schema permits an obvious pattern — mint generated products into an account-scoped feed (cache_scope: "account") so they acquire a feed_version — but no doc states it. Ask: document the intended pattern for dynamically generated products (account-scoped feed publication vs. proposal-path-only), and state whether a proposal allocation may reference a product present in no feed.

4. Is a hold-free seller profile conformant? The capabilities task-subset enum suggests a seller could advertise list_products + buy_products + request_proposals without refine_proposals/accept_proposal — i.e., no holds ever. Is that a supported profile, and what is the buyer's defined recourse when finalize is systematically unable? Ask: state whether partial task adoption is conformant per subset, and what buyers should expect from each declared shape.

None of these block the direction — they're the seams where two conformant implementations of the aggregator model would diverge today. Happy to help draft text for any of them.

[bokelley]

Thanks for the stress-test from the aggregator topology — exactly where these seams surface.

Q1 — Hold duration. expires_at is the spec's answer: the committed proposal carries the authoritative hold window, the buyer reads it before calling accept_proposal, and the decision to proceed with a short window is theirs to make. No protocol floor is specified, and that's intentional — a 5-minute aggregator hold (upstream reservation APIs unavailable until execute) and a 72-hour publisher IO desk hold are legitimately different products. The "cannot be rejected merely because reserved inventory was sold elsewhere" language is the flip side of the same contract: the seller bears the reservation obligation for the duration of expires_at. An optional typical_hold_seconds capability field enabling pre-finalize comparison is a reasonable patch-eligible follow-up, but its absence isn't an interop failure — two conformant implementations today produce the same wire shape, just with different expires_at values the buyer evaluates. Spec Backlog follow-up.

Q2 — Batch-finalize atomicity. The mixed-outcome question is already answered at the schema level: refine-proposals-response.json has an allOf constraint on results stating "If any result is finalized, every result MUST be finalized; a finalize batch either creates every requested hold or none." Mixed finalized/unable is schema-invalid — atomicity forbids it, and a refused batch returns all-unable. The concrete gap is narrower: MULTI_FINALIZE_UNSUPPORTED in error-code.json scopes its description and recovery hint exclusively to "get_products call (multiple action: 'finalize' entries in refine[])." A seller refusing cross-ad-server atomic finalize on refine_proposals today has no catalog-sanctioned code for that call site; a buyer implementing recovery on the new task surface has no signal to follow. The fix is a one-paragraph update — extending the enumDescription and the aliases recovery hint to cover refine_proposals refinements[] alongside get_products refine[]. @bokelley, this is within the PR's own error-catalog perimeter and worth catching before merge.

Q3 — On-the-fly products. The design is intentional: buy_products is the "accept published terms" path, and feed_version binds the acceptance to a specific snapshot. Products generated per-brief are designed for the proposal path — accept_proposal takes only proposal_id + proposal_terms_digest with no feed-version requirement; the seller resolves product terms within the committed snapshot. A proposal allocation can reference a product present in no public feed, and that's by design. The account-scoped feed pattern (cache_scope: "account" from list_products, returning a scoped feed_version) does enable buy_products for generated inventory — the schema permits it, but the docs don't state it. The needed text: "Products absent from the wholesale feed are designed for the proposal path; account-scoped feed publication is the optional direct-purchase enabler." Spec Backlog follow-up, naturally grouped with #6432.

Q4 — Hold-free profile. Partial task adoption is conformant by design. The x-legacy-fallback annotations on refine_proposals, accept_proposal, and buy_products all resolve to create_media_buy / get_products facades. A seller advertising list_products + buy_products + request_proposals without refine_proposals/accept_proposal is a valid profile — proposals stay in draft, and buyers fall back to create_media_buy with explicit packages. Naming the canonical task-subset profiles ("direct-purchase: list_products + buy_products"; "full proposal lifecycle: + request_proposals + refine_proposals + accept_proposal") is useful integrator guidance for #6432.

---

Q2 is the only item within this PR's own perimeter. Q1, Q3, and Q4 are Spec Backlog doc clarifications; tagging them together in a follow-up issue before merge would give them a clear landing zone.

---

Generated by Claude Code

[bokelley]

Follow-up commit acfe841 extends MULTI_FINALIZE_UNSUPPORTED to cover the refine_proposals call site introduced in AdCP 3.2.

What changed (static/schemas/source/enums/error-code.json):

1. enumDescriptions — rewrote the narrative from a single get_products-only sentence to a two-call-site description:

   Two call sites where this applies: (1) a get_products call with multiple action: 'finalize' entries in refine[]…; (2) a refine_proposals call with multiple action: 'finalize' entries in refinements[]…

2. enumMetadata.suggestion — extended the SDK recovery hint to name both surfaces:

   sequence single-proposal finalize calls — one finalize entry per get_products refine[] call or per refine_proposals refinements[] call

Why: The refine_proposals response schema already enforces the atomicity invariant ("if any result is finalized, every result MUST be finalized; a finalize batch either creates every requested hold or none"), so a seller whose downstream stack can't guarantee atomic cross-ad-server commit on refine_proposals had no catalog-sanctioned error code to return — the previous description only mentioned get_products.

---

Generated by Claude Code