feat(schemas): filter_diagnostics on get_products response

[bokelley]

Summary

Adds optional filter_diagnostics block to get-products-response.json — non-fatal observability for the filter-not-fail empty-result UX gap that both pre-build expert reviewers independently flagged on PR #3472.

The gap

Every required_* filter in AdCP is silent-exclude semantics (matches OpenRTB / SSP capability discovery patterns). When the result list is empty or unexpectedly small, the buyer can't distinguish:

• "No inventory matches the brief"
• "required_metrics excluded everything"
• "required_geo_targeting excluded everything"
• "budget_range had no overlap"

Today the buyer must blindly relax filters one at a time to find the unsatisfiable one.

Shape

{
  "products": [],
  "filter_diagnostics": {
    "total_candidates": 47,
    "excluded_by": {
      "required_metrics": { "count": 31, "values": ["completed_views"] },
      "required_geo_targeting": { "count": 9 },
      "budget_range": { "count": 7 }
    }
  }
}

• total_candidates: baseline before filters applied. May be sampled at large catalogs.
• excluded_by: keyed by filter property name; each value carries count (required), optional values (the filter values that contributed to exclusions), and optional notes.

Design decisions

• Counts only — never product names. Listing excluded products would leak competitive intel about adjacent campaigns. Counts plus filter values (inputs that did the excluding, not the products that got excluded) is enough for triage without that leakage.
• Counting semantics intentionally loose. Sellers vary on ANY-filter vs ONLY-this-filter counting. Spec documents counts as approximate triage signal, not exact accounting. Tightening would force every seller to implement the same filter-evaluation ordering — internal architecture AdCP shouldn't mandate.
• Observability, not error reporting. Sellers still silently exclude unmatched products per the filter-not-fail convention. This block is purely additive triage signal.

Backwards compatibility

Optional and additive. Sellers that don't populate the field, and buyers that don't consume it, see no change. Sellers without per-filter instrumentation adopt incrementally; absence is conformant.

Test plan

• npm run build:schemas — clean
• npm run test:schemas — 7/7
• npm run test:examples — 34/34
• npm run test:json-schema — 255/255
• npm run test:composed — 32/32
• npm run typecheck — clean
• precommit + pre-push — green

Closes #3482.

🤖 Generated with Claude Code