Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 11 additions & 5 deletions docs/reporting-source-adapters.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,11 @@ sealed, replayable reporting publication. Return `InlineFetchResult` when metric
availability differs within a constituent. Its `cell_availability` map is keyed
by **request constituent ID, then metric name**. Constituent IDs are not
necessarily media buy IDs; read them from `request.coverage.constituents`.
A package request uses `coverage.grain == "package_item"` and freezes its buy
selector in `coverage.media_buy_ids`. Each package constituent binds both
`media_buy_id` and `package_id`. An empty constituent list can represent a
complete package scan for the selected buys. For ordinary buy requests,
`request.media_buy_ids` derives the selected buys from the constituents.

```python
from adcp.reporting.inline_source import InlineFetchResult, MetricEvidence
Expand Down Expand Up @@ -117,11 +122,12 @@ Cell evidence cannot bypass that freshness gate.
Rows can omit missing, unsupported, or delayed metrics; available measurements
for other metrics are retained. A control total is a checksum over the staged
rows -- a consumer recomputes it from the revision's rows -- so it covers every
staged row, including rows outside the requested coverage, which stay staged
with a warning. It is emitted when every staged row carries a valid finite
numeric value for the metric. Missing fields, nulls, booleans, and invalid
numbers prevent a total, and an omitted explicit-zero row value is not filled
in. Statuses the SDK derives on its own withdraw nothing: a result with no
staged row. Package requests reject rows outside the exact requested
`(media_buy_id, package_id)` pairs before staging; buy requests retain the
warning behavior for outside rows. A total is emitted when every staged row
carries a valid finite numeric value for the metric. Missing fields, nulls,
booleans, and invalid numbers prevent a total. An omitted explicit-zero row
value is not filled in. Statuses the SDK derives on its own withdraw nothing: a result with no
`cell_availability` publishes exactly the totals it published before.

### The withdrawal invariant
Expand Down
54 changes: 52 additions & 2 deletions src/adcp/reporting/conformance.py
Original file line number Diff line number Diff line change
Expand Up @@ -34,10 +34,13 @@

import asyncio
import hashlib
import json
from collections.abc import Awaitable, Callable, Sequence
from datetime import datetime, timezone
from typing import Any, Literal, TypeVar

from pydantic import ValidationError

from adcp.reporting.source import (
AuthoritativeOfferingV1,
ProvisionalSnapshotOfferingV1,
Expand Down Expand Up @@ -152,9 +155,15 @@ async def _with_deadline(


def _validate_request_against_capabilities(
capabilities: ReportingSourceCapabilitiesV1, request: ReportingSourceSliceRequestV1
capabilities: ReportingSourceCapabilitiesV1,
request: ReportingSourceSliceRequestV1,
) -> ProvisionalSnapshotOfferingV1 | AuthoritativeOfferingV1:
"""Is this frozen slice an exact atomic offering of this executor build?"""
if request.contract_version != capabilities.contract_version:
raise _fail(
"CAPABILITY_MISMATCH",
"the executor must explicitly declare the request contract version",
)
if capabilities.scope != "effective_account":
raise _fail(
"CAPABILITY_MISMATCH",
Expand Down Expand Up @@ -200,6 +209,15 @@ def _validate_request_against_capabilities(

_validate_window_bounds(offering, request)

if (
request.coverage.grain == "package_item"
and "package_item" not in offering.constituent_kinds
):
raise _fail(
"CAPABILITY_MISMATCH",
"a package slice requires package_item support in the selected offering",
)

for constituent in request.coverage.constituents:
if constituent.product_id not in offering.product_ids:
raise _fail(
Expand Down Expand Up @@ -294,6 +312,8 @@ def _validate_manifest_against_request(
request: ReportingSourceSliceRequestV1,
manifest: SourceBatchManifestV1,
) -> None:
if manifest.manifest_version != request.contract_version:
raise _fail("MANIFEST_MISMATCH", "the manifest version must match the request version")
if request.coverage.expected == "full" and manifest.coverage.status != "full":
raise _fail(
"MANIFEST_MISMATCH",
Expand Down Expand Up @@ -376,6 +396,22 @@ def _validate_manifest_against_request(
request.coverage.denominator_fingerprint,
),
]
if request.coverage.grain == "package_item":
echoed.extend(
[
("coverage.grain", manifest.coverage.grain, request.coverage.grain),
(
"coverage.media_buy_ids",
manifest.coverage.media_buy_ids,
request.coverage.media_buy_ids,
),
(
"coverage.constituents",
[item.constituent for item in manifest.coverage.constituents],
request.coverage.constituents,
),
]
)
for field, actual, expected in echoed:
if actual != expected:
raise _fail(
Expand Down Expand Up @@ -470,12 +506,26 @@ async def validate_reporting_source_execution(
manifest_bytes = result.manifest_bytes
assert manifest_bytes is not None

if response.contract_version != request.contract_version:
raise _fail("MANIFEST_MISMATCH", "the execution response version must match the request")

if response.identity != request.identity:
raise _fail(
"IDENTITY_MISMATCH", "the response must echo the complete frozen request identity"
)

manifest = parse_verified_source_batch_manifest_v1(response.manifest, manifest_bytes)
try:
manifest = parse_verified_source_batch_manifest_v1(response.manifest, manifest_bytes)
except ValidationError as error:
payload = json.loads(manifest_bytes)
if (
isinstance(payload, dict)
and payload.get("manifest_version") != request.contract_version
):
raise _fail(
"MANIFEST_MISMATCH", "the manifest version must match the request"
) from error
raise
_validate_manifest_against_request(offering, request, manifest)

cancel = cancel or asyncio.Event()
Expand Down
2 changes: 2 additions & 0 deletions src/adcp/reporting/fixtures.py
Original file line number Diff line number Diff line change
Expand Up @@ -387,6 +387,8 @@ def redacted_completed_result(

coverage = SourceBatchCoverageV1(
denominator_fingerprint=request.coverage.denominator_fingerprint,
grain=request.coverage.grain,
media_buy_ids=request.coverage.media_buy_ids,
status="full" if available else "none",
constituents=[
ReportingConstituentCoverageV1(constituent=item, status=status, **evidence) # type: ignore[arg-type]
Expand Down
Loading
Loading