Skip to content

RFC: Hold extension, hold ranking, and holds on specific installments #8086

Closed

Description

@bokelley

Problem

AdCP 3.2 has one kind of hold: finalizing a proposal reserves its inventory until expires_at. #7661 lets a seller disclose its hold policy before finalize. Scheduled inventory that depends on a person (creator posts, podcast host-reads, episode sponsorships) needs four things the binary hold can't express.

  1. Extension. Buyers often need more time for legal review or client sign-off. Today the only path is to let the hold lapse and finalize again, which can lose the slot. RFC: disclose proposal hold policy before finalization #7661 explicitly says re-finalizing is not an extension mechanism.
  2. Ranking. Sellers of scheduled media routinely give a first hold to one buyer and a second hold to another. The second hold converts if the first is released or lapses. With right of first refusal, when the second holder wants to commit, the first holder gets a deadline to accept or release.
  3. Holds on a specific installment. For installment products, the thing being held is a specific post date or episode. Buyers need to see which installments are held and until when.
  4. Holds waiting on a person. A creator marketplace can't commit until the creator agrees. Finalize can run async (submitted), but there's no way to say "tentative hold, waiting on talent, expected by X".

Sketch for WG discussion

Use cases

  • A creator marketplace selling slots in creators' upcoming videos, where each slot needs the creator's yes.
  • Podcast host-read and episode sponsorships.
  • Linear and event sponsorships, where first and second holds are standard practice.

Related: #7661, #7620, #8010, #7777.

Activity

  1. added
    rfcProtocol change — auto-adds to roadmap board
    media-buyIssue concerns the media-buy protocol domain
    on Oct 9, 2026
  2. added
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Oct 9, 2026
  3. added this to the Spec Backlog milestone on Oct 9, 2026
  4. bokelley commented on Oct 9, 2026

    @bokelley
    ContributorAuthor

    Triage

    Classification: RFC
    Bucket(s): spec / protocol, media-buy
    Status: ready-for-human
    Milestone: Spec Backlog

    What the experts said:

    • ad-tech-protocol-expert: Items 3 and 4 are clean non-breaking additions; item 1's sketch violates proposal immutability — extend must produce a new committed proposal_id (same invariant as finalize), not mutate expires_at in place; item 1 also requires RFC: disclose proposal hold policy before finalization #7661 (hold_policy) as a prerequisite for normative max_extensions/total_hold_duration constraints; item 2 needs a new proposal.rank_changed webhook event type and normative scoping of holds[] to the authenticated buyer's own entries only (cross-buyer leakage risk).
    • adtech-product-expert: Item 4 is done — expected_confirmation_at on the submitted arm landed in 3.3 (PR feat(schema): add expected_confirmation_at to submitted media-buy envelopes #8016 merged). Items 1 and 3 solve real agentic gaps for scheduled media sellers. Item 2 (hold ranking / ROFR) carries high seller-side adoption friction — the hold_rank queue + rank-change notification + respond_by deadline is OMS-level state machine logic that most seller agents will route via ext instead — and ROFR deadline enforcement puts AdCP in the middle of a commercial dispute if either party contests the clock.

    My take: Item 4 is implemented; items 1 and 3 are worth doing once the sketch corrections below are incorporated. Item 2 is the WG call: advisory readback (Option A) vs. normative ROFR obligation (Option B).


    Decision memo (proposed — pending WG ratification)

    Class: normative
    Refs: #8086, #7661
    Dissent: none yet

    Item 4 — closed. expected_confirmation_at on submitted finalize arm covers the "waiting on talent" case. No additional surface needed.

    Item 3 — recommended. Add optional holds[] to committed proposal response, scoped to the authenticated buyer's own entries only.

    // committed proposal — per-installment hold readback (buyer's own entries)
    {
      "proposal_status": "committed",
      "expires_at": "2026-10-20T00:00:00Z",
      "holds": [
        { "installment_ref": "ep_042", "rank": 2, "expires_at": "2026-10-20T00:00:00Z" }
      ]
    }

    Item 1 — recommended with correction. Add extend action to refine_proposals; it MUST produce a new committed proposal_id (same immutability pattern as finalize, parent_proposal_id pointing back). Requires #7661 to land first.

    // refine_proposals: extend action on a committed source
    + { "action": "extend", "proposal_id": "prop_abc", "idempotency_key": "ext_001" }
    // response: new committed proposal_id, updated expires_at, or hold_unavailable
    + { "proposal_id": "prop_def", "parent_proposal_id": "prop_abc",
    +   "proposal_status": "committed", "expires_at": "2026-10-27T00:00:00Z" }

    Item 2 — WG decision needed:

    Option A — advisory hold_rank readback (no ROFR enforcement):

    { "proposal_status": "committed", "hold_rank": 2 }

    No new webhook events. ROFR stays bilateral. Low seller adoption friction; populate when supported.

    Option B — normative ROFR with proposal.rank_changed webhook:

    // committed proposal with ROFR deadline
    { "proposal_status": "committed", "hold_rank": 2, "respond_by": "2026-10-12T17:00:00Z" }
    // new webhook event
    { "event_type": "proposal.rank_changed", "proposal_id": "prop_abc",
      "hold_rank": 1, "respond_by": "2026-10-12T17:00:00Z" }

    New webhook event type + deadline enforcement required. Sellers implement full hold-queue state machine.

    Option A is the low-friction path; Option B provides richer buyer-side visibility but adds governance exposure and a new webhook primitive.


    Triaged by Claude Code. Session: https://claude.ai/code/session_01VGH8NA4vmCT1YJrp1ja6BR


    Generated by Claude Code

  5. added
    claude-triagedIssue has been triaged by the Claude Code triage routine. Remove to re-triage.
    needs-wg-reviewBlocked on a working-group decision — surface in WG meeting agendas
    and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Oct 9, 2026
  6. modified the milestones: Spec Backlog, 3.3.0 on Oct 9, 2026
  7. bokelley commented on Oct 9, 2026

    @bokelley
    ContributorAuthor

    WG decision brief (3.3)

    Agenda status: consent round. Objections by Fri 2026-10-16 23:59 UTC. This covers item 1 (hold extension) only. Items 2 and 3 are not in this slice, and item 4 was found not done: expected_confirmation_at is absent from the compact refine_proposals envelope, so it is tracked separately as slice #8086-A.

    Draft PR: #8097 (experimental media_buy.hold_extension, changeset minor). Single adopter: Availnet, a creator marketplace.

    Recommended shape: a new extend_hold action on refine_proposals. It targets a committed, unexpired proposal and forbids every revise field, like finalize. A batch containing it contains only extend_hold entries and is atomic. Success returns the existing finalized outcome with a new committed successor (parent_proposal_id = source, same commercial_terms and terms_digest, later expires_at). Failure is unable / hold_unavailable with batch_aborted siblings. Sellers declare media_buy.proposal_refinement.hold_extension: true; buyers MUST NOT send extend_hold otherwise.

    1. Does extension create a new committed successor (immutability, like finalize) rather than mutate expires_at in place? Recommend yes. A mutated expires_at would break proposal immutability and the parent_proposal_id lineage.
    2. After a successful extension the source is no longer acceptable (INVALID_STATE), and a failed extension leaves it and its hold untouched (yes / no)? Recommend yes. This avoids two live holds on one slot, and a failed extension never costs the buyer the hold it already has.
    3. Ship with no hold_policy fields, leaving limits as seller policy expressed through hold_unavailable, and keep RFC: disclose proposal hold policy before finalization #7661 in the backlog? Or pull RFC: disclose proposal hold policy before finalization #7661's min_duration into 3.3? Recommend yes, ship without hold_policy. RFC: disclose proposal hold policy before finalization #7661 has five open decisions and would put the whole proposal at risk.

    Known interaction: under #7954 terms_only, extend_hold extends the acceptance window. #7954 excludes hold_unavailable under terms_only, so the draft allows it for extension declines only; that needs reconciling when #7954 lands.

    Default if no objection by Fri 2026-10-16 23:59 UTC: the recommendation as drafted.

  8. 3 remaining items

  9. bokelley commented on Oct 12, 2026

    @bokelley
    ContributorAuthor

    Correction to the item 1 brief above

    Question 3 in the brief above recommended shipping extend_hold without hold_policy and leaving #7661 in the backlog. That has changed. #7661 has moved into 3.3 as #8140 (brief on #7661), and #8097 is now stacked on it. Question 3 now reads:

    1. Extension limits come from hold_policy (yes / no)? Recommend yes:
      • A seller extends a hold only when the proposal's hold_policy says extendable: true. Absent means false, and the seller declines with hold_unavailable.
      • The successor's expires_at must be no later than the original hold_placed_at plus max_total_duration, counted across the whole chain of extensions.
      • The successor carries hold_policy and hold_placed_at forward unchanged.
      • media_buy.proposal_refinement.hold_extension: true remains the agent-level gate for sending extend_hold at all.
      • Sellers that don't list media_buy.hold_policy keep limits as seller policy expressed through hold_unavailable.

    The known interaction with #7954 is now resolved. extend_hold applies only to committed proposals that hold inventory. Against a terms-only commitment, the seller fails the request at task level with INVALID_STATE, so terms-only sellers never return hold_unavailable.

    Questions 1 and 2 and the default are unchanged. #8097 now targets #8140's branch, so its diff shows only the extend_hold slice. It also adds compliance vectors for extension: within the ceiling, at the ceiling across two steps, past it, hold_placed_at carried forward, and declines.

  10. bokelley commented on Oct 14, 2026

    @bokelley
    ContributorAuthor

    Process update: this slice is merging to main now as experimental, so it ships in the 3.3 beta and can be tried hands-on. After the beta, the training agent will implement it (#8181), and the working group will then review all the related slices together, end to end, against working behaviour (hold policy #8140, extend_hold #8097, response collections #8141, follower counts #8098).

    As a result, Friday's date no longer locks anything in. Objections and comments on the questions above are still welcome here at any time, and the experimental label means the shape can still change with notice.

  11. bokelley commented on Oct 17, 2026

    @bokelley
    ContributorAuthor

    Items 2 and 3 are merged to main as experimental slices. Both ship in the 3.3 beta. The WG reviews them end to end with the rest of the hold work after the training agent supports them (#8181).

    • Item 2, hold ranking: feat(media-buy): experimental advisory hold ranking (rankable, hold_rank) #8255, feature id media_buy.hold_ranking, Option A (advisory).
      • hold_policy.rankable defaults to false. Without it, available: true still means an exclusive, first-position hold.
      • Under a rankable policy, the committed proposal carries hold_rank (1 = first). A live hold's position never gets worse, so a stale hold_rank is an upper bound on the buyer's real position.
      • Only the number of holds ahead is disclosed, never another buyer's identity or terms.
      • There's no right-of-first-refusal deadline and no rank-change webhook. Behind first position, accept_proposal may return PRODUCT_UNAVAILABLE or submitted.
    • Item 3, per-installment holds: feat(media-buy): experimental per-installment hold readback (holds) #8257, feature id media_buy.installment_holds.
      • A committed proposal's holds[] (product_id, installment_ref, and a per-entry hold_rank under a rankable policy) shows how the one all-or-none hold maps onto installments. It isn't a set of separate holds, so finalize stays atomic.
      • There's no per-entry expires_at.
      • holds[] is required only when the allocated products declare specific installments.

    Accepted as recommended, and not in these slices: a buyer-side require_first_position opt-out on finalize, which can be added later without breaking anything.

  12. removed
    needs-wg-reviewBlocked on a working-group decision — surface in WG meeting agendas
    on Oct 28, 2026
  13. bokelley commented on Oct 31, 2026

    @bokelley
    ContributorAuthor

    Shipped in 3.3 (experimental) first in 3.3.0-beta.0 via #8140 (hold_policy), #8097 (extend_hold), #8255 (advisory hold ranking), #8257 (per-installment holds[] readback) and #8104 (expected_confirmation_at on a submitted finalize). Decisions: #8086 (comment) (items 2 and 3) and #8086 (comment) (item 1).

    #8537 withdrew installment selection to 4.0 but left these features in place. The end-to-end WG review of the hold slices waits on the training agent and compliance work, which stay open as #8181 and #8182.

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

    claude-triagedIssue has been triaged by the Claude Code triage routine. Remove to re-triage.media-buyIssue concerns the media-buy protocol domainrfcProtocol change — auto-adds to roadmap boardspec / protocol

    Type

    No type

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions