feat(media-buy): external audience sources on sync_audiences (#6540)

[bokelley]

Implements #6540 — the runtime leg of the audience-activation surface (#4324 / #6549), experimental under the same media_buy.audience_activation feature id. WG approved the audience work for 3.2 as experimental.

What this adds

An audience on sync_audiences carries either inline member deltas or a source reference — a pointer to buyer data the seller ingests over a declared activation rail. Data never transits AdCP.

• core/audience-source.json (new, experimental): dataset (grantee-identified share the seller reads — Snowflake Secure Data Sharing, Databricks D2D, BigQuery authorized views; optional declarative access_expires_at) | platform_segment (binds a vendor-distributed segment to an audience_id; segment_ref is the vendor's ID as issued to the buyer, seller owns the ingest-side mapping).
• Request: source on the audience object; schema-enforced mutual exclusion with add/remove.
• Response: source echo (never credentials) with access_status (active/unavailable) and columns_read; last_synced_at schema-required exactly when counts populate (ready/too_small) so every count has an anchor — first-read-pending (processing) and failed-first-ingest stay legal.
• SOURCE_ACCESS_FAILED on both error-code surfaces, error.field-keyed recovery: bad reference (fix request) vs. missing grant (grant + retry) vs. vendor outage (backoff).
• Docs: full external-sources section on sync_audiences (flows, canonical column contract, refresh vs. replication lag, latency band); present-tense updates to every "until RFC: external audience sources — pass-through references on sync_audiences #6540 lands" placeholder; canonical experimental-list row extended.
• Tests: tests/audience-external-sources.test.cjs (12) wired into the chain.

Normative rules from the RFC review threads

1. Transport fixed at creation — cross-transport upserts rejected with CONFLICT (error.field: audience_id); convert by delete-and-recreate.
2. Loss of source access MUST NOT change audience status — the seller cannot distinguish revocation from expiry from a transient outage (all three observables are a failed read), so membership freezes at last successful read and stays targetable, last_synced_at freezes, and failed re-reads MUST NOT emit suspended (reserved for consent/policy causes, which remain orthogonal). Health reports via source.access_status.
3. Access expiry is not deletion — bounds the access window, not retention; DPA governs; teardown stays delete: true.
4. Single pane — sourced audiences appear in discovery identically to pushed ones; no new list task.
5. Capability gate — source kinds map 1:1 to declared activation patterns; undeclared kinds → UNSUPPORTED_FEATURE; credential material → CREDENTIAL_IN_ARGS; grantee-identified flows only.

Validation

Schema build, 12/12 new tests, example validation, error-code lint (both enum surfaces), oneOf audit, and compliance links all green on a tree rebased onto the merged #6549.

Closes #6540.

🤖 Generated with Claude Code

[aao-secretariat]

Medium: Description says last_synced_at is "REQUIRED when source is present," but the if/then two hunks down only requires it when status is ready/too_small — and the docs lifecycle rule scopes it the same way ("Required on sourced audiences whenever counts are populated (ready/too_small)"). A sourced audience in processing has source present with nothing synced yet, and the test at tests/audience-external-sources.test.cjs:612 correctly asserts it validates without last_synced_at. The normative field text is stricter than both the enforcement and the docs. Tighten it: "REQUIRED once counts populate (status ready/too_small)."

[aao-secretariat]

Ladon verdict: Escalate to human review

Escalate — gated schema paths require human/CODEOWNERS approval.

This PR adds an experimental runtime leg of audience activation (#6540): a new discriminated core/audience-source.json, a source request field with schema-enforced mutual exclusion vs add/remove, a response source echo, and a new SOURCE_ACCESS_FAILED error code. Schema, changeset scope (minor, protocol-scoped), oneOf discrimination, and schema↔docs coherence largely hold. No critical or high findings were reported, so the diff itself is not blocking.

However, this PR modifies/adds files under static/schemas/source/**, which are under a hard, deterministic approval gate (gated_paths: true), and review_decision is REVIEW_REQUIRED — not APPROVED. Per decision rule row 2, the outcome must be escalate until a real human/CODEOWNERS approval satisfies the gate.

Medium findings (non-blocking, worth a look during human review):

• static/schemas/source/media-buy/sync-audiences-response.json:116 — last_synced_at description overstates its requirement relative to its own if/then and the docs (normative-text mismatch).

Escalation reasons:

• Gated schema paths touched (e.g. static/schemas/source/core/audience-source.json, static/schemas/source/media-buy/sync-audiences-request.json, sync-audiences-response.json, enums/error-code.json) and review_decision is REVIEW_REQUIRED. Human/CODEOWNERS approval required before merge.

Medium findings

• static/schemas/source/media-buy/sync-audiences-response.json:116 — last_synced_at description overstates requirement vs its own if/then and the docs

Why human review

• Gated paths touched under static/schemas/source/** (audience-source.json added; sync-audiences-request/response.json, error-code.json, audience-activation-method.json modified) and review_decision is REVIEW_REQUIRED — human/CODEOWNERS approval required before this can merge.
• This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/core/audience-activation-method.json (modified) matches static/schemas/source/**; static/schemas/source/core/audience-source.json (added) matches static/schemas/source/**; static/schemas/source/enums/error-code.json (modified) matches static/schemas/source/**; static/schemas/source/media-buy/sync-audiences-request.json (modified) matches static/schemas/source/**; static/schemas/source/media-buy/sync-audiences-response.json (modified) matches static/schemas/source/**) and the current GitHub review decision is 'REVIEW_REQUIRED', not APPROVED. This is a hard gate enforced in code — Ladon cannot auto-approve until a human/CODEOWNERS approval is recorded, regardless of how clean the diff is.

[aao-secretariat]

Ladon verdict: Escalate to human review

Escalate — gated schema paths require human/CODEOWNERS approval.

This PR modifies/adds files under static/schemas/source/** (audience-source.json added; sync-audiences-request/response.json, error-code.json, audience-activation-method.json modified), which sit behind a hard, non-overridable approval gate. review_decision is not APPROVED (unknown/none), so per decision rule row 2 the gate is not satisfied and the outcome must be escalate.

No blocking (critical/high) findings surfaced in this run. The prior medium finding on sync-audiences-response.json:116 is outside the current delta and not re-raised. The delta since the prior pass — a new SOURCE_ACCESS_FAILED disposition (held-for-next-minor, target 3.2) plus definition-count bumps (583→584, 152→153) for the single new audience-source definition — is internally consistent and lint-valid. This is a net-clean iteration, but the gated-paths gate still stands until a human/CODEOWNERS approval is recorded.

Escalation reasons:

• Gated paths touched under static/schemas/source/** and review_decision is not APPROVED — human/CODEOWNERS review required before merge.

Why human review

• Touches gated paths under static/schemas/source/** (audience-source.json added; sync-audiences-request.json, sync-audiences-response.json, error-code.json, audience-activation-method.json modified) and review_decision is not APPROVED — human/CODEOWNERS approval required before this can merge (decision rule row 2, hard gate).
• This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/core/audience-activation-method.json (modified) matches static/schemas/source/**; static/schemas/source/core/audience-source.json (added) matches static/schemas/source/**; static/schemas/source/enums/error-code.json (modified) matches static/schemas/source/**; static/schemas/source/media-buy/sync-audiences-request.json (modified) matches static/schemas/source/**; static/schemas/source/media-buy/sync-audiences-response.json (modified) matches static/schemas/source/**) and the current GitHub review decision is 'unknown', not APPROVED. This is a hard gate enforced in code — Ladon cannot auto-approve until a human/CODEOWNERS approval is recorded, regardless of how clean the diff is.