feat(reporting): support per-constituent, per-metric source availability

[bokelley]

Summary

InlineFetchResult can describe coverage only per constituent. InlineReportingSource._seal_manifest() then assigns that constituent status to every requested metric cell.

Real ad-server adapters often have uneven metric support. A GAM result may provide impressions, spend, and clicks while video-completion or viewability metrics are unsupported, delayed, or unmeasured for the same media buy. The current interface forces the adapter to overclaim all metrics, underclaim all metrics, or drop useful measurements.

Proposed surface

Add a typed per-constituent/per-metric evidence map to InlineFetchResult, with helpers that keep the common all-covered case concise. One possible shape:

InlineFetchResult(
    rows=rows,
    metric_availability={
        (media_buy_id, "impressions"): MetricEvidence.present(data_through=watermark),
        (media_buy_id, "completed_views"): MetricEvidence.unavailable("not_video_inventory"),
    },
)

Omitted cells can retain today's derived constituent behavior for backward compatibility. Explicit cell evidence should override that default and should be validated against the frozen requested constituent/metric matrix.

Acceptance criteria

• An inline source can independently mark every requested constituent/metric cell as present, explicit zero, missing, delayed, or unavailable with the required evidence/reason.
• Only requested constituent/metric keys are accepted; duplicates, unknown metrics, and unknown constituents fail clearly.
• The SDK still supplies semantic-contract identity from the selected offering rather than asking adapters to duplicate it.
• Rows may honestly omit unavailable/missing metrics, and control totals are emitted only where complete and valid.
• Helper constructors cover common patterns such as “all metrics present,” “one metric unsupported everywhere,” and “metric delayed through watermark.”
• Bare row lists and existing InlineFetchResult callers retain current behavior.
• Conformance tests prove a single constituent can have impressions present, clicks explicit-zero, viewability delayed, and completed views unavailable in one sealed manifest.

Adopter impact

Embedded Sales Agent is adding GAM delivery metrics beyond impressions/spend. This evidence is necessary to expose all available adapter metrics without pretending every metric is measurable on every inventory type. The same interface should work for FreeWheel and future adapters.

[bokelley]

Triage

Classification: Feature request
Bucket(s): handlers (inline reporting source adapter)
Status: ready-to-implement
Milestone: omitted

What the experts said:

• code-reviewer: non-breaking, correct "partial" promotion approach; two blockers in the proposed surface (tuple keys aren't JSON-safe, evidence() closure must branch on cell status not constituent roll-up), plus missing matrix-validation and an explicit_zero guard
• dx-expert: InlineFetchResult.metric_availability name-collides with the wire-format field on SourceBatchManifestV1 — rename to cell_availability; nits on tuple-key orientation and MetricEvidence constructor enforcement

My take: The manifest layer already supports per-cell statuses (ReportingMetricAvailabilityV1) and the "partial" constituent status in _CONSTITUENT_ALLOWS_METRIC was built for exactly this mixed case — the feature just needs to be wired up. All existing InlineFetchResult(rows=rows) callers retain current behavior because the new field defaults to None.

Implementation scope:

• New MetricEvidence frozen dataclass with classmethods present(data_through: datetime), unavailable(reason: str), delayed(reason: str), explicit_zero(); validate invariants in __post_init__ (present requires data_through, unavailable/delayed require reason).
• New cell_availability: Mapping[str, Mapping[str, MetricEvidence]] | None = None on InlineFetchResult (name: cell_availability, not metric_availability — that name is taken by the wire-format field on SourceBatchManifestV1, line 1310 of source.py; silently wrong if swapped). Shape: {constituent_id: {metric_name: evidence}}.
• Update _derive_statuses() — when cell_availability is set, resolve each (constituent_id, metric_name) cell from it; promote constituent status to "partial" when its metric statuses are mixed (i.e., not all the same and not all {"present", "explicit_zero"}). Validate all keys against the requested matrix and raise a clear ValueError for unknown constituent IDs or metric names.
• Update _seal_manifest() — route the evidence() helper on cell status, not the constituent roll-up status: a "present" cell must emit {"data_through": ...}, a "delayed" or "unsupported" cell must emit {"reason": ...}, regardless of what the constituent roll-up is. Add an explicit comment on the explicit_zero hoist that "partial" constituents are excluded from that path (line ~617).
• Add convenience helpers on InlineFetchResult or as module-level functions: all_present(data_through), metric_unsupported_everywhere(metric_name, reason), metric_delayed_through(metric_name, watermark).
• Files: src/adcp/reporting/inline_source.py (sole production change); new conformance tests covering: (a) the 4-status cell case (impressions=present, clicks=explicit_zero, viewability=delayed, completed_views=unavailable in one sealed manifest), (b) unknown-key rejection, (c) backward-compat with bare rows.

---

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

---

Generated by Claude Code