feat(media-buy): add demographic delivery reporting

[bokelley]

Summary

• add opt-in reporting_dimensions.demographic controls and by_demographic delivery rows
• reuse the existing demographic-system vocabulary and expose product-level support
• document the contract and add focused validation coverage

Validation

• focused demographic delivery contract tests
• JSON schema and composed schema suites
• MCP schema projection/context bounds
• docs navigation and schema-link checks
• full precommit suite (1,043 canonical tests; 6,127 server tests)

Closes #5680

[aao-secretariat]

Ladon verdict: Escalate to human review

Escalate — gated path change without required review approval.

This PR modifies four files under static/schemas/source/**, which are under the repo's hard, path-based approval gate (gated_paths: true). The current review_decision is REVIEW_REQUIRED, not APPROVED, so the gate is not satisfied and the PR cannot be auto-approved (decision rule row 2).

The change itself is a clean, additive Normative (non-breaking) change: adds an opt-in demographic reporting dimension to get_media_buy_delivery (request reporting_dimensions.demographic, response by_demographic/by_demographic_truncated) and a supports_demographic_breakdown capability on both reporting-capabilities surfaces. It mirrors the existing by_audience shape, reuses the shipped demographic-system enum, carries a correct minor changeset, and adds a focused Ajv contract test. Schema↔docs coherence, oneOf ratchet, and released-artifact immutability all clear. This is Normative (non-breaking), not Breaking-class, so the breaking-change hard gate does not independently apply — but the deterministic gated-paths gate does.

No blocking (critical/high) findings. Only a single low finding (missing additionalProperties: true on the new request dimension), which does not block.

Escalation reason: touches gated schema-source files and requires human/CODEOWNERS review before merge.

Medium findings: none.

Why human review

• Modifies gated schema-source files (static/schemas/source/core/canonical-reporting-capabilities.json, static/schemas/source/core/reporting-capabilities.json, static/schemas/source/media-buy/get-media-buy-delivery-request.json, static/schemas/source/media-buy/get-media-buy-delivery-response.json) while review_decision is REVIEW_REQUIRED — human/CODEOWNERS approval required before merge.
• This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/core/canonical-reporting-capabilities.json (modified) matches static/schemas/source/**; static/schemas/source/core/reporting-capabilities.json (modified) matches static/schemas/source/**; static/schemas/source/media-buy/get-media-buy-delivery-request.json (modified) matches static/schemas/source/**; static/schemas/source/media-buy/get-media-buy-delivery-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-source files require human/CODEOWNERS approval before merge.

This PR is an additive, non-breaking demographic delivery breakdown: a new by_demographic response array + by_demographic_truncated flag (allOf over delivery-metrics, matching the existing by_audience/by_placement shape), a demographic request dimension, supports_demographic_breakdown on both capability surfaces, docs updated in lockstep, a minor changeset, and a contract test. The reviewer verified schema↔docs coherence, changeset scope/type, enum reuse, and the oneOf audit — no blocking, Medium, or load-bearing Low findings.

However, the PR modifies four files under static/schemas/source/**, which are under a hard, deterministic approval gate (gated_paths: true), and the current review_decision is REVIEW_REQUIRED, not APPROVED. Per decision-table row 2, this must escalate regardless of how clean the diff is. The gate lifts automatically once a human/CODEOWNERS approval is recorded.

Escalation reasons

• Modifies gated schema-source files while review_decision is REVIEW_REQUIRED — human/CODEOWNERS approval required before merge.

No new critical/high/medium findings surfaced in this run; the escalation persists solely on the unsatisfied gated-paths condition.

Why human review

• Modifies gated schema-source files (static/schemas/source/core/canonical-reporting-capabilities.json, static/schemas/source/core/reporting-capabilities.json, static/schemas/source/media-buy/get-media-buy-delivery-request.json, static/schemas/source/media-buy/get-media-buy-delivery-response.json) under a hard approval gate while review_decision is REVIEW_REQUIRED — human/CODEOWNERS approval required before merge.
• This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/core/canonical-reporting-capabilities.json (modified) matches static/schemas/source/**; static/schemas/source/core/reporting-capabilities.json (modified) matches static/schemas/source/**; static/schemas/source/media-buy/get-media-buy-delivery-request.json (modified) matches static/schemas/source/**; static/schemas/source/media-buy/get-media-buy-delivery-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.