feat(media-buy): dependency-impact cluster + webhook foundation (3.1)

[bokelley]

Summary

Lands the impairment side of the dependency-impact cluster (#2853) and the foundational webhook contracts (#4582 tracks 1–2) that tie every push channel to its read API. Result of a design walk that narrowed #2853 from a single at_risk + impacts[] field into a four-axis taxonomy (impairment / defect / advisory / performance) — this PR ships impairment + the foundation; defects (#4586) and advisories (#4587) are spun out to their own epics.

Two review cycles applied — protocol, product, docs, and code reviewer feedback consolidated into the current state.

Media-buy health surface (#2855, #2856)

• enums/media-buy-health.json — ok | impaired, orthogonal to media-buy-status. A paused/pending/active buy can each be impaired without affecting status. default: "ok" on the field.
• core/impairment.json — package-scoped dependency state change. Materiality: package_ids minItems: 1; MUST-strength for resource types where the resource→buy join is cheap (audience, event_source, property), SHOULD for creative and catalog_item where the pool join is expensive.
• enums/impairment-reason-code.json — flat shared enum; per-resource-type valid subset documented in enumDescriptions. Categorical reasons only — the typical remediation paths live in the lifecycle doc (see below).
• enums/impairment-offline-state.json — canonical offline values referenced by impairment.transition.to (was open string in the first draft). The resource_type ↔ offline_state pairing is enforced by impairment.coherence (compliance: impact.coherence assertion across media-buy and resource status #2859), not the JSON Schema.
• core/media-buy.json gains health + impairments[]. Synchrony: snapshot MUST reflect the impairment within 5 minutes of observed_at regardless of buyer poll cadence (closed the gap where "next sync" had no max-staleness bound).
• enums/notification-type.json gains impairment. Minimal factual enumDescriptions added for the four pre-existing values (scheduled, final, delayed, adjusted) so generators don't produce partial docs.

Resource-level offline states (#2838, #2857, #2858)

• audience-status: adds suspended for seller-initiated offline transitions (closes audience-sync: seller-initiated archival / suspension not modeled #2838).
• creative-status: enumDescriptions clarify approved → rejected is a valid post-approval transition (creative-status: clarify approved → rejected transition post-approval #2857).
• catalog-item-status: adds withdrawn for seller-initiated removal — distinct from rejected (no buyer-side resubmit path).
• event-source-health: documents that insufficient covers source-offline; disambiguate via events_received_24h: 0.
• Property depublication verified via brand.json / adagents.json — no per-property status field needed.

Foundation docs (#4582 tracks 1–2)

• New docs/protocol/snapshot-and-log.mdx — five-rule contract for push/pull duality:
  • Rule 1: dedupe transport retries by idempotency_key; correlate fires to state by notification_id. Two distinct ids, distinct purposes — same notification_id under different idempotency_keys = re-emission signal (missed-events warning), not retry.
  • Rule 2: every push event has a snapshot delta. No webhook-only state.
  • Rule 3: at-least-once delivery; snapshot is authoritative.
  • Rule 4: either path is complete. Buyer using webhooks reliably gets all data; buyer using only GET gets the same data. Holds today for state events; partial for data-bearing events (delivery report fires) — get_media_buy_delivery: windowed-breakdown parity with reporting_webhook frequency #4590 closes the gap for get_media_buy_delivery in 3.1.
  • Rule 5: push events and log entries share an id space.
• docs/building/by-layer/L3/webhooks.mdx adds Persistent channel contract section — at-least-once delivery, no-ordering, per-event-type coalescence windows (5min default for impairment; sub-minute for latency-sensitive subclasses like fraud/brand-safety; defer to seller capabilities for shorter), replay-via-snapshot, mutability via update_*, auth renewal, termination.
• docs/media-buy/media-buys/lifecycle.mdx documents the health surface, materiality coverage (MUST vs SHOULD by resource type), reverse-direction rule, impairment.coherence invariant, the operational-vs-commercial non-goal, and a Remediation by reason_code table (moved here from enumDescriptions on reviewer feedback — SDK generators emit enum descriptions as type-doc comments; normative remediation guidance belongs in narrative docs).

Why this lands as one PR

The design walk on #2853 surfaced that the original RFC was implicitly defining its own webhook contract. Rather than ship that contract twice (#2261 creative lifecycle has the same need), the webhook foundation (#4582) was extracted as a separate epic. This PR coordinates both sides because (a) the impairment schemas reference the snapshot/log doc, (b) reviewers benefit from seeing the full design landing intact, and (c) splitting would have forced six small PRs through six review cycles.

Additive across the board — no breaking changes. Buyers that exhaustively switch on media-buy-status see no change (no new status value); buyers that read media-buy.health get the new dependency-health signal alongside their existing status handling.

Test plan

• npm run build:schemas — clean
• npm run test:schemas — 7/7 pass
• npm run test:examples — 36/36 pass
• npm run test:json-schema — 256/256 pass
• npm run test:composed — 40/40 pass
• npm run test:unit — 887/887 pass
• npm run test:error-codes — clean
• npm run test:storyboard-check-enum, test:storyboard-doc-parity — clean
• npm run check:registry — 14 entries OK
• Pre-push: docs validation + version sync — pass
• Two expert review passes (protocol / product / docs / code) — all actionable items applied

Follow-up tickets (deliberately not in this PR)

• get_media_buy_delivery: windowed-breakdown parity with reporting_webhook frequency #4590 — get_media_buy_delivery: windowed-breakdown parity with reporting_webhook frequency (closes Rule 4 for data events; capability-scoped MUST so mid-size SSPs declare honestly rather than degrade webhook frequency).
• webhook envelope: type notification_id as a first-class field #4594 — type notification_id as a first-class envelope field (closes the prose-not-typed gap; SDK generators currently don't surface notification_id).
• compliance: impact.coherence assertion across media-buy and resource status #2859 — impairment.coherence conformance tooling (spec language is in this PR; assertion implementation is a separate code change).
• storyboard: dependency-impact end-to-end scenario #2860 — dependency-impairment storyboard (depends on this PR landing first).
• RFC: Webhook foundation for AdCP (epic) #4582 tracks 3–7 — per-account subscription model, generalized log surface, auth/transport hygiene, conformance, replay primitive evaluation.
• snapshot-and-log positioning — first-pass docs reviewer asked whether this earns top-level /docs/protocol/ placement or should be renamed to "The contract for push channels" and demoted. Filed as a follow-up to debate post-merge rather than block.

Refs #2838, #2853, #2855, #2856, #2857, #2858, #4582. Spin-outs: #4586, #4587.

🤖 Generated with Claude Code

[bokelley]

Expert review pass — addressed in 92fd09c

Ran the PR through four reviewers (ad-tech protocol, ad-tech product, docs, code). Consolidated the high-signal items into one fix commit. Headline issues and what landed:

Blockers fixed

• x-entity: impairment unregistered (code reviewer) — added to x-entity-types.json enum and x-entity-definitions.
• adcp_version apparent downgrade (protocol reviewer) — false alarm; main is already at 3.0.3, the prior commit reconciled in-tree drift. No regression.

High-signal protocol gaps closed

• Max-staleness budget on synchrony (protocol — "the actual gap"). media-buy.impairments[] description now states the snapshot MUST reflect the impairment within 5 minutes of observed_at regardless of buyer poll cadence. Closes the loophole where "next sync/poll response" without a bound let snapshots lag arbitrarily.
• impairment_id removal semantics (protocol — deferral was unsafe). Closing webhook fire MUST reuse the same impairment_id as its notification_id; a new impairment for the same resource gets a new id. Receivers reconcile open-vs-closed via the snapshot, not via a separate id.
• Materiality MUST/SHOULD split (product — mid-size SSP enforceability). MUST for resource types where the resource→buy join is cheap and 1:N (audience, event_source, property); SHOULD for creative and catalog_item where the pool join is expensive. Plus explicit "MAY report conservatively when uncertain; MUST NOT report when serving is provably unaffected."
• transition.from now optional. Handles cases where the seller never observed the prior state (e.g., property depublished discovered via brand.json crawl).
• additionalProperties: true on impairment.json (code reviewer). Aligns with the rest of core/ — published schemas are durable contracts.

Docs cleanup

• Operational vs commercial non-goal (product — first contracted-buy implementer would otherwise build a dispute pipeline against impairments[]). New section in lifecycle.mdx: impairments are operational signals; commercial remedies route through accountability_terms.
• Materiality coverage section in lifecycle.mdx explains the MUST/SHOULD split for implementers.
• "When you'd be right to push back" wrapped in non-normative <Note> and moved below the gaps section (docs — agent retrieval landing on push-back framing as a sanctioned exception).
• Coherence seam fixed (docs). Both snapshot-and-log.mdx and webhooks.mdx now state webhook_activity[] is for debugging and "buyers MUST NOT rely on it for state reconciliation; that's what the snapshot is for."
• Feature-named link text for #4278 / #2261 references so anchors don't go stale when those land.
• Removed invented enumDescriptions for pre-existing scheduled/final/delayed/adjusted values (code reviewer). Only the new impairment value carries a description in this PR.

Deferred / acknowledged

• snapshot-and-log.mdx positioning (docs reviewer — "earns the foundation positioning vs. reads as RFC-justification?"). Real question, but the answer is a design discussion that shouldn't block merge. Two options: rename to "The contract for push channels" and demote from top-level /docs/protocol/, or invest a generalization pass against non-webhook surfaces. Filing as a follow-up after merge.
• Coverage self-declaration (product reviewer — for sellers that don't compute the full materiality join). Useful but a separate capability and bigger surface; deferring to a future RFC rather than expanding scope here.
• Remediation hooks (product reviewer — suggested_substitutes[], signals-agent handoff). Out of scope for this PR; the protocol delivers structured paging, not structured remediation. Worth a separate ticket if buyer agents accumulate concrete asks.

What reviewers explicitly endorsed

• Orthogonal health vs. extending media-buy-status — protocol: "right call, file this debate as closed." Product: "every DSP has some 'running but something's wrong' indicator; buyers will map this cleanly."
• Snapshot/log + persistent webhook contract — product: "production-grade, will be cited for years."
• Shipping impairment-only (deferring defect/advisory to RFC: Resource defect signals (epic) #4586/RFC: Seller advisory / recommendation signals (epic) #4587) — product: "right sequencing — only axis with unambiguous owner + trigger."

Diff is small (7 files, +27 -17). Ready for another look.

[bokelley]

Sharpening pass on the foundation contract

Three additional items from a follow-up review — all hit the snapshot/log doc.

1. Two ids, not one (Rule 1 conflation)

Doc previously read as if notification_id was the only id. Receivers couldn't distinguish "got the same fire twice via transport retry" (uninteresting) from "seller re-emitted the open impairment because my receiver was down for 4 hours" (signal — missed events warning).

Now explicit:

• idempotency_key — per-fire, transport-layer. Receivers dedupe to suppress retries.
• notification_id (= impairment_id for impairment events) — per-state-event. Stable across re-emissions of the same logical event.
• Same notification_id with different idempotency_keys = re-emission, not retry. Buyer should treat as missed-events warning.

The transport-layer split already existed in the protocol (idempotency_key is documented in webhooks.mdx). My doc collapsed them; now it doesn't. impairment.json schema description matches.

2. Replay rule narrowed to state events (Rule 4 honesty)

Previously stated as universal: "Replay = re-read the snapshot." Holds for state-shaped events (impairment, lifecycle, status). Doesn't hold for data-bearing events (delivery report fires) — get_media_buy_delivery returns the cumulative integral, not the per-fire differential. A buyer who misses a delivery fire can see the aggregate moved but loses the per-window detail.

Doc now explicitly differentiates:

• State events → full snapshot recovery (rule holds today)
• Data events → snapshot reflects cumulative only; per-fire detail may be lost; webhook_activity[] (RFC: Buyer-side webhook delivery visibility on get_media_buys #4278) is the path to making the rule universal

Rule 4 is now positioned as the destination, not a uniform present-day claim. Pretending it held universally today would invite buyers to build recovery paths that silently lose data.

3. Coalescence is per-type, not flat (5min ceiling was wrong)

Previously: "Window SHOULD NOT exceed 5 minutes." Wrong for latency-sensitive impairment subclasses — a fraud-impairment receiver cannot wait 5min for coalescence to flush.

Now a per-event-type table:

Event type	Default	Notes
impairment (general)	5min	Resource-state impairments
impairment (latency-sensitive)	sub-minute / no coalescence	Fraud, brand safety — MUST NOT apply general default
Future advisory	hours to daily	High noise tolerance
Future defect	minutes to hours	Between impairment and advisory

Sellers MAY declare shorter via get_agent_capabilities. Sellers MUST NOT exceed per-type default without buyer opt-in.

Diff summary

Three files: docs/protocol/snapshot-and-log.mdx, docs/building/by-layer/L3/webhooks.mdx, static/schemas/source/core/impairment.json. All test-clean (schemas + examples + unit).

[bokelley]

Two-paths principle — replacing the "snapshot is authoritative" framing

Reviewer point: prior framing made webhooks read as authoritative-for-reporting (pub/sub-ish) with the snapshot as a degraded fallback. Wrong direction — pulls the architecture toward "broker is truth" when AdCP is REST-with-events (Stripe/GitHub model).

The principle

Either path is complete. A buyer using webhooks reliably gets all the data. A buyer using only GET gets the same data. The two paths are at parity in content and granularity; the buyer chooses based on latency, ergonomics, and receiver infrastructure.

This is now Rule 4 of the snapshot/log doc, replacing the old "replay = re-read" framing.

Today's gaps closed in 3.1

State events — holds today. Missed impairment → re-read get_media_buys, snapshot fully reconstructs.

Reporting (data-bearing events) — partial today. Two specific gaps:

1. get_media_buy_delivery: windowed-breakdown parity with reporting_webhook frequency #4590 (filed) — get_media_buy_delivery needs windowed pulls. If reporting_webhook fires hourly, the GET must accept window_granularity: hourly and return per-window slices matching the webhook payload. Today it returns daily breakdowns + cumulative aggregates only. The fix is additive: new request params + new windows[] response array + capability declaration.
2. RFC: Buyer-side webhook delivery visibility on get_media_buys #4278 (existing) — webhook_activity[] for per-fire transport observability. Closes "did the webhook hit my endpoint?" — debugging surface, not data recovery.

Both land in 3.1. Once they do, Rule 4 is uniform — every channel has full pull parity.

Why this matters more than the prior framing

Without two-paths-equal, AdCP is REST for some channels and pub/sub for others, and buyers building against the contract have to know which model applies where. That's the architecture the reviewer was worried about — and they're right to be.

The fix isn't to make webhooks more authoritative. It's to make the GET path complete for the channels where it isn't yet. That's a smaller, cleaner spec lift (one new field on one tool plus capability), and it preserves the snapshot-authoritative direction that matches how every modern API does it.

Doc edits

• docs/protocol/snapshot-and-log.mdx Rule 4 rewritten to two-paths framing. "Where the surface doesn't yet follow this" section updated with both get_media_buy_delivery: windowed-breakdown parity with reporting_webhook frequency #4590 and RFC: Buyer-side webhook delivery visibility on get_media_buys #4278 as the close-out path.
• docs/building/by-layer/L3/webhooks.mdx replay section clarifies webhook_activity[] is debugging, not data recovery. Missed reporting fire → wait for get_media_buy_delivery: windowed-breakdown parity with reporting_webhook frequency #4590 to land, then pull per-window.

Filed

• get_media_buy_delivery: windowed-breakdown parity with reporting_webhook frequency #4590 — get_media_buy_delivery: windowed-breakdown parity with reporting_webhook frequency. 3.1 target.

[bokelley]

Addressed both diff comments + walk-back on structured remediation

Diff comment #1 — resource_type coining "resource" as a new concept

Tightened the field description on core/impairment.json. The values are the existing x-entity vocabulary (audience, creative, catalog_item, event_source, property) — not a new typology, just the subset of x-entity types whose offline state can impair serving. Description now says this explicitly so we don't drift into formalizing "Resource" as a separate AdCP abstraction.

Diff comment #2 — transition.to open string vs. canonical enum

New schema enums/impairment-offline-state.json — single shared enum of the canonical offline values: suspended | rejected | withdrawn | insufficient | depublished. transition.to now $refs it. Per-value enumDescriptions document which resource_type each is valid for.

The resource_type ↔ offline_state pairing is enforced by impairment.coherence (#2859) — same layer where all cross-resource pairing validation already lives. JSON Schema constraint at the field stops typos and case-sensitivity drift; coherence assertion stops resource-type/offline-state mismatch.

transition.from stays as open string (each resource_type has its own serviceable-state vocabulary; same coherence assertion validates).

Walk-back: dropped structured suggested_action idea

Brian flagged that for many reason codes (creative rejected, audience suspended) the buyer's remediation path is the same one they used at campaign setup — they already know which tool to call. A structured suggested_action.action_tool would either state the obvious or overreach into campaign-level judgment the seller can't make (is this creative load-bearing? does removal break the rotation math?).

The right boundary: seller knows what happened; buyer knows what it means for the campaign.

Approach: enrich impairment-reason-code.json enumDescriptions with "Typical remediation:" lines per code — protocol-level guidance, documented once, no per-impairment seller burden. E.g.:

content_rejected: "Previously-approved creative content was re-reviewed and rejected. Applies to: creative. Typical remediation: same path as initial creative approval — fix the issue and resubmit via sync_creatives. Buyer's campaign-level decision (replace with an alternate creative vs. wait for resubmit approval) depends on creative pool composition and is left to the buyer."

impairment.remediation stays as optional free-text on the impairment for seller-specific context that doesn't belong in protocol-level enum docs (e.g., "we restored this audience yesterday; sync now to pick up the refresh").

Files

• static/schemas/source/enums/impairment-offline-state.json (new)
• static/schemas/source/core/impairment.json (resource_type description + transition.to $ref + transition.from clarification)
• static/schemas/source/enums/impairment-reason-code.json (Typical remediation: lines per code)

Schema + example tests clean.

[bokelley]

Second expert-review pass — applied

Ran the PR through the four reviewers again (protocol / product / docs / code). Consolidated the actionable items into one commit. Headlines:

Docs (snapshot-and-log.mdx)

• Rule 1 lead-with-imperative (docs flag — coding agents retrieving "how do I dedupe?" were landing on three paragraphs of why before the do this). Now starts: "Dedupe transport retries by idempotency_key. Correlate fires to state by notification_id."
• Rule 4 MUST → SHOULD-with-promotion (protocol flag — the rule told implementers they were already non-compliant on something whose schema support is six weeks out via get_media_buy_delivery: windowed-breakdown parity with reporting_webhook frequency #4590). Once get_media_buy_delivery: windowed-breakdown parity with reporting_webhook frequency #4590 lands and is adopted, SHOULD promotes to MUST for declared windowed_pull_granularities.
• Trimmed "load-bearing for the protocol" advocacy line (docs flag).
• Note typing of notification_id via webhook envelope: type notification_id as a first-class field #4594 (protocol flag — notification_id was documented in prose but not declared as a typed envelope field; SDK generators wouldn't surface it).

Schema

• impairment-reason-code.json — stripped "Typical remediation:" lines from enumDescriptions (docs flag — verbose normative prose in enum value docstrings conflates value-definition with guidance; SDK generators emit these as docstring/godoc on the enum value). Clarified seller_removed vs withdrawn vs policy_violation boundary (code flag).
• notification-type.json — re-added minimal factual enumDescriptions for scheduled / final / delayed / adjusted (code flag — was silently producing missing docstrings for 4 of 5 values). These are short factual descriptions, not invented semantics.
• media-buy.json health — added default: "ok" and wrapped $ref in allOf to allow the sibling default keyword (code flag — description claimed defaulting but schema didn't enforce).
• impairment.json transition.from — added pattern: "^[a-z][a-z0-9_]*$" (protocol flag — blocks free-form garbage while keeping vocabulary open per resource_type).

Lifecycle doc

• New "Remediation by reason_code" table in lifecycle.mdx. The typical-remediation prose moved here from enumDescriptions. SDK generators get clean categorical reasons in the enum; humans/agents reading the lifecycle docs get the remediation paths. The pii_audit_failed row in the table now correctly reflects that buyers MUST wait for the seller to clear the audit before re-syncing — protocol expert flagged the prior phrasing as a buyer-agent loop hazard.

Issues

• get_media_buy_delivery: windowed-breakdown parity with reporting_webhook frequency #4590 updated — capability-scoped MUST (product flag — strict MUST would force mid-size SSPs with stream-tap webhook architectures to downgrade webhook frequency to dodge the requirement; honest declaration via windowed_pull_granularities capability is the right answer). Renamed window_granularity → time_granularity (product flag — industry naming matches DV360 groupBy: HOUR, TTD TimeBreakdown, Xandr equivalents).
• webhook envelope: type notification_id as a first-class field #4594 filed — type notification_id as a first-class envelope field. Closes the gap protocol expert flagged: receivers building strictly from JSON Schema wouldn't see notification_id in their type definitions today.

Reviewer endorsements this pass

• Two-paths principle reads as honest contract, not marketing — the ✅ Holds today / ⚠️ Partial today pairing and the "until get_media_buy_delivery: windowed-breakdown parity with reporting_webhook frequency #4590 lands" callout earn foundation positioning.
• Two-id model is buildable from the docs alone — receiver logic ("dedupe on idempotency_key; upsert state on notification_id; flag re-emission") is unambiguous.
• transition.to enum + from open + impairment.coherence pairing validation is the right split between field-level constraint and conformance-assertion enforcement.
• Walk-back from structured suggested_action is correct — buyer agents will hardcode reason_code → tool mappings regardless; enumDescriptions make those mappings consistent across agents (that's the actual interop win).
• get_media_buy_delivery: windowed-breakdown parity with reporting_webhook frequency #4590's windows[] shape matching webhook payload is correct — makes the "either path is complete" claim verifiable instead of aspirational; costs sellers nothing since the serializer is already written.

Acknowledged-but-deferred

• Move "Typical remediation:" out of enumDescriptions entirely — done; now lives in lifecycle.mdx table.
• enumDescriptions are now doing normative work (product flag) — true. Bar for changing them post-3.1 should be enum-value-change level (back-compat review), not "doc tweak." Worth a separate note in spec-guidelines but doesn't block this PR.

Files in this pass

docs/protocol/snapshot-and-log.mdx, docs/media-buy/media-buys/lifecycle.mdx, static/schemas/source/enums/impairment-reason-code.json, static/schemas/source/enums/notification-type.json, static/schemas/source/core/media-buy.json, static/schemas/source/core/impairment.json.

Schema + example tests clean.