update_media_buy: implement revision → CONFLICT optimistic concurrency (deferred from #1546)

[numarasSigmaSoftware]

Summary

update_media_buy does not implement the revision optimistic-concurrency field. The pinned AdCP spec (3.1.0-beta.3) makes this a MUST: per media-buy/update-media-buy-request.json and the SDK type (adcp==5.7.0 UpdateMediaBuyRequest.revision):

"Expected current revision for optimistic concurrency. When provided, sellers MUST reject the update with CONFLICT if the media buy's current revision does not match. Obtain from get_media_buys or the most recent update response."

This was the one part of the envelope-tolerance review on #1546 (Blocker 3) intentionally deferred, because — unlike the sibling fixes (context echo, idempotency-key preservation) that shipped in that PR — it is a migration-bearing concurrency feature, not a mechanical change.

Current state (as of #1546)

• There is no revision column on the MediaBuy ORM model, and no compare logic.
• revision is currently stripped by the envelope-tolerance layer (ADCP_ENVELOPE_FIELDS in src/core/request_compat.py) because no wrapper / request model declares it, so update_media_buy(revision=N, ...) reaches the impl with revision=None.
• _update_media_buy_impl never consults revision.

Net effect: a buyer that pins revision for safe concurrent editing gets a silent success instead of the spec-mandated CONFLICT on a stale write.

Scope / acceptance criteria

1. Migration — add a revision integer column to MediaBuy (Alembic; non-empty upgrade()/downgrade(), single head). Initialize existing rows to 1.
2. Plumb the field — declare revision on the update_media_buy MCP wrapper, A2A raw/handler, and the internal UpdateMediaBuyRequest, so the envelope-tolerance middleware no longer strips it (it strips only ADCP_ENVELOPE_FIELDS a tool does not declare).
3. Enforce transactionally — in the update path, compare the request's revision against the media buy's current revision under the same transaction; raise a typed CONFLICT on mismatch; increment the stored revision on success.
4. Echo revision — return the current revision on the update_media_buy response, and on get_media_buys responses (the spec names both as the source of the next expected revision).
5. Tests — mismatch → CONFLICT wire envelope; matching revision → success + increment; concurrent-update race (two updates carrying the same stale revision → the second gets CONFLICT). Mutation-verify each pin. Cite the authoritative schema (dist/schemas/3.1.0-beta.3/media-buy/update-media-buy-request.json) and note whether the conformance storyboard grades it.

Related (lower priority)

Full idempotency replay-dedup for sync_accounts. #1546 restored end-to-end preservation of the client idempotency_key, but _sync_accounts_impl still does not consult it for dedup (the idempotency_attempt repository already exists). Wiring replay-dedup here is a natural companion to the revision work.

References

• PR feat: AdCP 3.1.1 version negotiation, envelope tolerance, and bearer normalization (#1512) #1546 (envelope-tolerance review; context-echo + idempotency-key-preservation fixes landed there)
• Issue fix: MCP tools reject AdCP adcp_version/adcp_major_version negotiation fields — agent uncallable by official AdCP SDK clients #1512 (AdCP version-negotiation / envelope tolerance)
• Spec: dist/schemas/3.1.0-beta.3/media-buy/update-media-buy-request.json (revision → CONFLICT); core/version-envelope.json @ v3.1.0-beta.3

[numarasSigmaSoftware]

Scope expansion: sync idempotency has no execution semantics (from PR #1546 second-round review)

The second-round review escalated the idempotency gap beyond the revision work already tracked here. PR #1546 restored end-to-end preservation of the client idempotency_key, but there is still no execution of the at-most-once contract. This issue should also cover:

• sync_accounts dedup is not wired. _sync_accounts_impl never reads req.idempotency_key; repeated same-key calls execute twice. Wire it through the existing replay infra — IdempotencyAttemptRepository (find_by_key / record_success, payload hash, cached-response replay, different-payload conflict) + the MediaBuyUoW.idempotency_attempts UoW — exactly as create_media_buy does (_handle_idempotency_race). The (agent, account, key) scope and RFC-8785 payload hashing are already implemented; reuse, don't rebuild.
• REST drops the key. SyncAccountsBody (src/routes/api_v1.py) has no idempotency_key field, so REST clients can't send it at all. Add it and forward.
• Key length is unvalidated. SyncAccountsRequest.idempotency_key (src/core/schemas/account.py) accepts empty/short values; the pinned sync schema requires 16–255 chars. Add the constraint.
• sync_creatives exposes no key at any transport (src/core/tools/creatives/sync_wrappers.py + REST SyncCreativesBody); the middleware silently strips its required key.

Acceptance: cross-transport (MCP/A2A/REST) tests asserting a repeated same-key request produces one mutation and one set of side effects, plus a different-payload-same-key conflict.

Spec: pinned 3.1.0-beta.3 sync request schemas (16–255-char key, at-most-once).