You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
feat(reporting): support per-constituent, per-metric source availability #1170
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:
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.
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.
Activity
bokelley commentedon Sep 15, 2026
Triage
Classification: Feature request
Bucket(s): handlers (inline reporting source adapter)
Status: ready-to-implement
Milestone: omitted
What the experts said:
"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 anexplicit_zeroguardInlineFetchResult.metric_availabilityname-collides with the wire-format field onSourceBatchManifestV1— rename tocell_availability; nits on tuple-key orientation andMetricEvidenceconstructor enforcementMy take: The manifest layer already supports per-cell statuses (
ReportingMetricAvailabilityV1) and the"partial"constituent status in_CONSTITUENT_ALLOWS_METRICwas built for exactly this mixed case — the feature just needs to be wired up. All existingInlineFetchResult(rows=rows)callers retain current behavior because the new field defaults toNone.Implementation scope:
MetricEvidencefrozen dataclass with classmethodspresent(data_through: datetime),unavailable(reason: str),delayed(reason: str),explicit_zero(); validate invariants in__post_init__(present requiresdata_through, unavailable/delayed requirereason).cell_availability: Mapping[str, Mapping[str, MetricEvidence]] | None = NoneonInlineFetchResult(name:cell_availability, notmetric_availability— that name is taken by the wire-format field onSourceBatchManifestV1, line 1310 ofsource.py; silently wrong if swapped). Shape:{constituent_id: {metric_name: evidence}}._derive_statuses()— whencell_availabilityis 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 clearValueErrorfor unknown constituent IDs or metric names._seal_manifest()— route theevidence()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 theexplicit_zerohoist that"partial"constituents are excluded from that path (line ~617).InlineFetchResultor as module-level functions:all_present(data_through),metric_unsupported_everywhere(metric_name, reason),metric_delayed_through(metric_name, watermark).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