Document revision and confirmed_at semantics in media buy response models

[bokelley]

Context

While validating bokelley/salesagent#631, we added revision and confirmed_at to the seller implementation for create/get/update media buy flows and found the expected semantics are easy to get subtly wrong without SDK-level guidance.

Semantics we needed

• revision is an optimistic concurrency token for media-buy mutations.
• create returns the initial revision, usually 1, when a seller-side media buy is minted synchronously.
• update returns the new revision after a mutating update.
• clients should pass the last observed revision as expected_revision on mutation when available, and retry/reload on conflict.
• confirmed_at is the seller commitment/confirmation timestamp, not a delivery-state timestamp. It should remain stable across pause/resume and other later state transitions.
• pending/manual approval flows may have confirmed_at = null until seller commitment happens.

Proposed SDK work

• Ensure create/get/update response model docstrings/comments describe these fields consistently.
• Add client-facing docs or examples showing expected_revision usage on update.
• Add tests/fixtures showing that confirmed_at is preserved after later updates rather than recalculated from current status.

Acceptance criteria

• SDK generated/reference docs explain revision as the media-buy concurrency token.
• SDK generated/reference docs explain confirmed_at as seller commitment time.
• At least one example demonstrates reading revision from create/get and passing it to update.

Discovered in

• fix: Add media buy revision concurrency controls bokelley/salesagent#631

[bokelley]

Triage

Classification: Bug (helper default) + Enhancement (docs/examples/tests)
Bucket(s): documentation (no client or handlers label found in repo)
Status: ready-for-human
Milestone: omitted

What the experts said:

• docs-expert: All proposed items are non-breaking; the confirmed_at description on get_media_buys_response says "A successful create_media_buy response constitutes order confirmation" — this implies the field is always non-null after create, directly contradicting pending/manual-approval flow semantics.
• dx-expert: Found an active bug in src/adcp/server/responses.py:418 — media_buy_response() uses confirmed_at or _rfc3339_now(), so sellers building on this helper always emit a non-null confirmed_at, even in pending flows where it should be null until seller commits.

My take: Four items land in three tiers. (1) Helper default confirmed_at or _rfc3339_now() → needs a human call: changing this to default None is a breaking default-value change; options include removing the auto-set, adding an explicit opt-in kwarg, or a deprecation path. (2) confirmed_at field description fix + revision completeness (mention update also returns a fresh revision) — non-breaking, ready to implement. (3) Example showing create → read revision → pass to update → handle conflict, and a test asserting confirmed_at is stable across pause/resume — non-breaking, ready to implement.

Flagging for @bokelley: should the confirmed_at helper auto-set be removed directly (calling it a bug fix) or does it need a deprecation cycle?

---

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code