Creative revisions: versioned updates, staged hot-swap for live creatives, re-review semantics, cross-seller correlation

[pkras]

Problem

The creative protocol has no revision model. Four gaps compound into one operational wall:

1. No versioning. sync_creatives upserts overwrite in place. No revision identifiers, no history, no rollback — only created_date/updated_date. "What changed between the last two versions of this creative" is unanswerable at the protocol level.
2. Update-vs-live-delivery is a wall, not a workflow. Creatives assigned to active, non-paused packages cannot be updated (INVALID_STATE); documented guidance is "pause the package first, or create a new creative version" with a different creative_id (sync_creatives best practices Welcome to adcp Discussions! #1/Rename Audience Activation Protocol to Signals Activation Protocol #6). Real ops need a hot-swap path — e.g. legal demands a disclaimer change on a live campaign — where the update goes through review while the current version keeps serving. Minting a new creative_id also severs the delivery-reporting join.
3. Re-approval after edit is unspecified. The status lifecycle covers rejected → processing on resubmit, but says nothing about an approved creative that is updated. Every seller will do something different, and some will keep serving materially changed content without re-review.
4. No cross-seller revision correlation. After trafficking to three sellers, an update is three independent syncs with three independent re-reviews and no shared identifier to answer "revision X is live on A, pending on B."

Proposed direction

Follow the native-localization precedent: capability-gated, sync_creatives-only mutation contract with strict readback, list_creatives authoritative.

Principles

• A revision is a new state of a creative, not a new creative. creative_id stays the join key for delivery, billing, assignments; revision_id identifies the content state.
• Revision identity is buyer-assigned (like creative_id, locale_variant_id). Syncing the same revision_id to N sellers gives cross-seller correlation for free — reconciliation is per-seller list_creatives reads, no central object.
• Approval attaches to content, not the creative ID. Material change (assets, localization, format identity) invalidates prior review; non-material change (name, tags) never does.
• Live creatives update through staging, never in place. With creative.supports_staged_updates, a material update to an actively delivering creative is accepted as a staged revision with its own review status; the approved revision keeps serving until the staged one is approved, then the seller promotes it atomically.

Surface sketch

• Capabilities: creative.supports_revisions, creative.supports_staged_updates (implies the former). Non-supporting sellers behave exactly as today.
• sync_creatives: optional creatives[].revision { revision_id, notes }; revisions immutable once accepted (REVISION_CONTENT_MISMATCH on reuse with different content; identical content is idempotent). Staged acceptance surfaces as action: "staged".
• Readback: current_revision_id, staged_revision { revision_id, status, synced_at }, and list_creatives include_revisions → revisions[] { revision_id, synced_at, action, status, notes }. History is metadata; per-revision asset retention is seller-optional; diffing is buyer-side.
• Normative re-review rule independent of the new capabilities: a material update to an approved creative MUST NOT be servable before re-review (new lifecycle edge approved → processing/pending_review); sellers MAY fast-path content identical to a previously approved revision — which is also the rollback path (re-sync prior content under a new revision_id).
• creative.status_changed webhook gains optional revision_id + staged so pushes identify which revision transitioned.

Compatibility: all new fields optional; seller mints revision IDs when older buyers omit them; the action enum gaining "staged" is the only change pinned consumers must opt into; older sellers keep today's pause-or-remint workflow, detectable via capabilities.

Out of scope

• Multi-party / buyer-side approval chains and structured review feedback (separate proposal — creative collaboration).
• Per-revision delivery-metric splits in get_creative_delivery (revision boundaries recoverable from promotion timestamps).
• A protocol-level content diff format.

[bokelley]

Triage

Classification: Feature request (RFC)
Bucket(s): spec / protocol, creative
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: Architecture is sound and follows the localization precedent cleanly; four points need resolution before implementation: idempotency_key × revision_id ordering contract, a forward-compat normative note on creative-action.json, a staged promotion failure contract, and patch-ineligibility of the re-review MUST — all elements target 3.2 minor, nothing is 3.1.x-eligible.
• ad-tech-protocol-expert-deep: Three WG questions before an implementation brief can be written: (1) the buyer-initiated material update path (approved → processing) collides with the existing webhook initiator constraint (buyer is explicitly excluded); (2) the re-review MUST rule has no conformance surface without a normative materiality definition; (3) revision_id immutability breaks under seller-side asset transcoding unless identity is explicitly scoped to input content, not processed output. Recommends factoring gap 3 as an independent fast-track 3.2 normative item.
• adtech-product-expert: Operational realism is medium. The hot-swap use case is real but concentrated in premium direct-deal scenarios; staged promotion has no OpenRTB/VAST/GAM precedent and most SSP creative review pipelines are batch/async, making supports_staged_updates a capability few sellers will advertise. Recommends a 3-piece split: gap 3 as fast-track normative 3.2 text, lightweight revision_id pass-through for gaps 1 + 4, and staged promotion as a separate experimental RFC.

My take: All three experts converge — the four gaps are real, the capability-gating architecture is sound and idiomatic, and all elements belong in 3.2 as a minor. Gap 3 (normative re-review MUST) is the highest-urgency piece and should be tracked independently; gaps 1, 2, and 4 require WG resolution of three open questions before implementation can begin.

---

Decision Memo (DR-PENDING — pending WG ratification)

---
id: DR-PENDING
title: Creative revision RFC targets 3.2 minor; gap 3 is a fast-track
       3.2 normative item; three design questions require WG resolution
class: normative
status: recorded
date: 2026-08-10
decided: ~2026-08
decided_by: WG ballot (pending ratification)
refs: ["#6347"]
dissent: none recorded
---

Decision: The creative revision RFC (#6347) is approved for inclusion in the 3.2 milestone as a minor additive change. Gap 3 (normative re-review MUST rule) should be extracted and tracked as a standalone fast-track 3.2 normative item. The staged promotion model (gap 2) must carry x-status: experimental in its first release. Gaps 1, 2, and 4 require resolution of three WG questions before an implementation brief is written.

Rationale: All proposed additions are non-breaking (new optional fields, new enum values, new capabilities following the localization precedent). None are 3.1.x patch-eligible — a 3.1.0-conformant seller that does not re-review on buyer material updates would newly fail the MUST (fails the IETF errata-vs-bis test). Staged promotion has no industry precedent; experimental designation lets two or three publisher partners validate the serving-layer contract before the spec stabilizes.

---

Three WG questions requiring resolution

WG-Q1 — Materiality definition: Who determines "material" at the wire level?

Option A — Normative field-level list (assets/localization/format_kind changes are material; name/tags/ext are not):

// Material — triggers re-review:
{ "creative_id": "ft_88201", "assets": { "banner_image": { "url": "new-banner.png" } } }

// Non-material — no re-review required:
{ "creative_id": "ft_88201", "name": "Updated Name", "tags": ["q3_2026"] }

Enables conformance testing. Constrains seller content policy.

Option B — Seller discretion (MUST rule applies; seller determines materiality per policy):

// Same wire shape — seller A may re-review; seller B may not. No conformance surface.
{ "creative_id": "ft_88201", "assets": { "banner_image": { "url": "new-banner.png" } } }

Zero adoption friction. Re-review MUST is unverifiable in interop testing.

Option C — Buyer hint with seller override:

 {
   "creative_id": "ft_88201",
   "assets": { "banner_image": { "url": "new-banner.png" } },
+  "material_change": true
 }

Buyer signals intent; seller retains override authority. Adds new request field.

---

WG-Q2 — Webhook initiator contract for buyer-initiated material updates: When a buyer submits a material update, the creative goes approved → processing. The subsequent processing → pending_review leg is seller/system-initiated and currently fires creative.status_changed. Existing buyer handlers interpret that transition as a first-submission outcome — not a re-review of a buyer update. WG must specify: (a) which legs fire the webhook on this path, (b) what initiator and reason_code are REQUIRED (content_drift is currently defined as seller-detected drift, not buyer-submitted changes), and (c) whether a new reason code is needed.

---

WG-Q3 — revision_id identity under seller-side asset processing:

Option A — Input-content identity (immutability checked against buyer payload before processing):

// REVISION_CONTENT_MISMATCH fires only when buyer sends different bytes.
// Seller transcoding does not affect identity. Cross-seller correlation holds.
{ "revision_id": "rv_2026_q3_v2", "assets": { "video": { "url": "https://cdn.acme/hero.mp4" } } }

Option B — Output-content identity (immutability checked against post-processed content):

// Seller A stores H.264; Seller B transcodes to VP9.
// Same buyer input → two different post-processed fingerprints.
// Cross-seller correlation fails for transcoded video/image assets.

If output-identity is chosen, cross-seller correlation (gap 4) is the buyer's responsibility; the spec should say so explicitly.

---

Settled by this memo:

• 3.2 minor is the correct version target for all elements.
• Gap 3 can ship independently ahead of the full revision machinery.
• Staged promotion (creative.supports_staged_updates) MUST carry x-status: experimental in first release.
• Buyer-assigned revision_id federated architecture is sound (no central registry needed, consistent with idempotency_key design).
• creative-action.json MUST carry a forward-compat normative note (receivers MUST treat unknown action values as forward-compatible additions) before "staged" ships — currently missing.

---

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

---

Generated by Claude Code

[bokelley]

Proposed WG decision packet for 3.2

To keep the protocol understandable, this should be decided as two independent questions: revision identity and staged activation. Accepting revision identity should not implicitly approve a serving-orchestration state machine.

Vocabulary and ownership

creative_id                         durable buyer creative / delivery join key
  └─ revision_id                   immutable buyer-authored input state
       └─ variant_id               seller-authored execution derived from that revision

• A buyer content edit creates a new revision_id; it is never represented as a seller variant.
• Seller transcoding or normalization does not create a new revision.
• Seller selection, contextualization, or serve-time generation may create a variant_id, which references its source revision_id.
• build_variant_id remains a pre-trafficking creative-generation candidate. If selected, it may be synced as a revision; it is not itself the revision identity.
• A revision is an identifier and review boundary inside the existing creative resource—not a new top-level resource or task.

Decision A — Core revision contract in 3.2

Recommendation: accept.

The 3.2 contract would include only:

1. Optional buyer-assigned revision_id on sync_creatives, immutable for a given buyer input payload. Reusing it with different buyer content fails; seller-side processing does not affect identity.
2. Seller echo/readback of the accepted revision and correlation from any delivered variant_id to its source revision.
3. creative_id remains stable across revisions and remains the assignment, delivery, and billing join key.
4. A new revision containing content-bearing changes cannot become servable using an earlier revision's approval. It must pass review first. Metadata-only changes such as name or tags do not create a new revision.
5. Older buyers and sellers retain today's behavior when revision_id is omitted or unsupported.

Explicitly deferred: a standalone revision resource/task, content diffs, retained revision payloads, general history APIs, revision-level delivery reporting, and arbitrary lineage graphs.

WG vote A: Include this core revision contract in 3.2? Yes / No

Decision B — Staged activation in 3.2

Recommendation: defer to a separate experimental RFC. Revision identity and re-review safety solve interoperable identity/approval problems without requiring sellers to implement serving-layer orchestration.

If the WG wants staging in 3.2, constrain it to the smallest possible capability-gated model:

• at most one active revision and one staged revision;
• the active approved revision keeps serving during staged review;
• approval promotes the staged revision atomically;
• no scheduled activation, rollback API, multiple pending revisions, or protocol-managed history;
• first release marked experimental.

WG vote B: B1 — defer staging (recommended), or B2 — include the minimal experimental model above.

Resulting implementation order

After vote A, write the core schema/docs/conformance PR. Only write staged-update schema changes if vote B selects B2. This keeps the 3.2 core independently implementable and prevents revision_id from being blocked on unresolved hot-swap mechanics.