Skip to content

negotiation: support extend_hold in refine_proposals preflight and verification #1904

Open

Description

@bokelley

Problem

adcp.negotiation doesn't support the experimental extend_hold refinement action (media_buy.hold_extension). The spec has had it since before 3.3.0-beta.5, and it's in the pinned 3.3.0-beta.6 bundle.

  • Buyer preflight refuses it. preflight_refine_proposals reports invalid_request_schema ("action must be explicitly set to revise or finalize") for a schema-valid extend_hold entry. Through refine_proposals_verified, and through the seller-side preflight_refinement_batch_or_raise, a valid request therefore fails before transport, or with VALIDATION_ERROR on the seller.
  • Response verification would fail a successful extension. verify_refine_proposals_response has no extend_hold entry in its action → outcome table. It accepts hold_unavailable / batch_aborted only for finalize. Its outcome == "finalized" checks require a draft source and unchanged terms, but a successful extend_hold reports finalized against a committed source.
  • No atomic transaction on the seller. execute_refinement_batch requires finalize_transaction only for finalize batches. An extend_hold batch, also all-or-none, would run without one.

Found while adopting beta.6 (#1901). Admitting extend_hold in preflight alone would have half-supported it, so that change was left out.

Spec reference (3.3.0-beta.6)

  • media-buy/refine-proposals-request.json refinements: "extend_hold … MUST target a committed, unexpired proposal that holds inventory and creates a committed successor with a later expires_at; a batch containing extend_hold MUST contain only extend_hold entries and is atomic." There's also an allOf if/then that enforces the single-action batch.
  • media-buy/proposal-refinement.json oneOf: the extend_hold branch (x-status: experimental). Like finalize, it forbids change_kind, constraints, product_changes, installment_changes, alternatives, ask, criteria and remove_media_buy_frequency_cap.
  • media-buy/refine-proposals-response.json outcome: "finalized also reports a successful extend_hold: the proposal is the new committed successor whose parent_proposal_id is the extended source and whose expires_at is the later deadline."
  • enums/proposal-refinement-reason.json: hold_unavailable covers a declined extension ("A failed extend_hold leaves the source proposal and its hold unchanged"), and batch_aborted covers "the all-or-none finalize or extend_hold batch".
  • Capability: proposal_refinement.hold_extension on get_adcp_capabilities.

Fix sketch

  1. Preflight.
    • Accept extend_hold.
    • Forbid the revision fields on it, as on finalize.
    • Apply the single-action batch rule to extend_hold.
    • Gate it on the seller's hold_extension capability when one is declared.
  2. Verification.
    • Add extend_hold: {finalized, unable} to the outcome table.
    • Allow hold_unavailable / batch_aborted for extend_hold.
    • Split the finalized checks by action. For extend_hold, require a committed source, a successor with the source as parent_proposal_id, a later expires_at, and unchanged terms (digest equality with the source), within the hold policy where it's declared.
  3. Seller helper. Treat an extend_hold batch as atomic, so it requires finalize_transaction or an extend-hold equivalent. Add a source-state check (committed and unexpired) next to validate_finalize_source_states_or_raise.
  4. Tests. Cover a valid batch, a mixed batch, an extension refused with hold_unavailable, and a successful extension verified against a committed source.

Code locations (next at 807141962)

  • src/adcp/negotiation.py:
    • preflight_refine_proposals (272): the action check (349), finalize-only forbidden fields (368), the mixed-batch rule (420).
    • verify_refine_proposals_response (571): the mixed-batch outcome rule (676), allowed_outcomes (705), the hold_unavailable / batch_aborted check (729), outcome == "finalized" verification (826) with its draft-source requirement (858).
  • src/adcp/decisioning/negotiation.py: validate_finalize_source_states_or_raise (101, finalize-only at 108), and execute_refinement_batch (273), whose transaction requirement keys on is_finalize (297).
  • Related docs that already mention extend_hold-only batches: src/adcp/server/responses.py:935, src/adcp/decisioning/context.py:643.

Activity

  1. added
    bugSomething isn't working
    no-triageSkip the Claude triage bot — human or designated agent will handle this issue
    sdk-10SDK 10 (next branch, AdCP 3.3)
    on Nov 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingno-triageSkip the Claude triage bot — human or designated agent will handle this issuesdk-10SDK 10 (next branch, AdCP 3.3)

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions