Skip to content

Commit 011db8f

Browse files
bokelleyclaude
andauthored
test(reporting): drive the whole Core lifecycle over docker Postgres (#1155)
* test(reporting): drive the whole Core lifecycle over docker Postgres Adds an end-to-end conformance test: a simulated reporting source drives `ReportingProducer`, which writes `PgReportingLedgerStore`, which `ReportingStatusHandler` projects onto the wire, which this SDK's *own* buyer-side `reconcile_reporting_core` then reconciles. That last hop is the point. The buyer half was written against the spec, not against this producer; if the seller's projection is wrong, the buyer's reconciler says so in the same terms a real buyer would. The payload is also validated against the generated `GetReportingStatusResponse`, so "the seller emits valid AdCP" is asserted rather than assumed. The narrative: install a config → close a period (obligation committed before any source data exists) → obligation visible and reconciliation not yet definitive → source answers, immutable revision committed → exact read with the binding independently recomputed → a genuinely empty period commits a zero-row revision and satisfies its obligation → a period the source never answers for has none → that period reads delayed, then action_required → a restatement supersedes rather than edits. Two further tests cover why the buyer derives its own denominator (a seller that simply omits a period returns a complete-looking, internally consistent ledger) and that Core reconciliation refuses a managed-delivery ledger rather than quietly trusting evidence it never verified. Writing it against the generated types found four real projection gaps, now fixed: obligations and revisions were missing `coverage`; revisions were missing the content-addressed definition binding, scope, and period; every view was missing the envelope `status`; periods were missing their `source_timezone`; and `scope` / `obligation_counts` did not match the schema. `scope` now derives from configuration generations rather than from whichever obligations landed on a page, so every page of one cursor reports an identical denominator. Two behavioral fixes the test forced: - A restatement needs a new observation identity. The source execution key now includes the committed revision count, so a *retry* replays the sealed publication (count unchanged) while a *restatement* genuinely re-reads the source (count advanced). The ordinal comes from durable state, not the clock. - Control totals preserve the source's declared decimal scale instead of normalizing "4.80" to "4.8", and the integer/decimal choice is made per metric rather than per value — otherwise a money total would flip type on the days it happened to land on a whole number. An integral float carries no scale (the wire's `10` arrives as `10.0`), and a non-finite value yields no total at all. `sync_reporting_status` is exercised through the vendored preview models, with an explicit TODO(rc.2) to re-drive it through `adcp.types` once the tag is cut — the same generated-type round trip the `get_reporting_status` test does. Runs against Postgres 16 via `ADCP_PG_TEST_URL`; skips without it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(reporting): drive sync_reporting_status through the generated types The lifecycle test's `TODO(rc.2)` is discharged. `sync_reporting_status` is in the published AdCP 3.2.0-rc.2 bundle, so the consumer-status batch no longer goes through vendored preview models: it is built with `adcp.types.SyncReportingStatusRequest` and the result is asserted to parse as `adcp.types.SyncReportingStatusResponse`. That matches the generated-type round trip `test_the_status_projection_validates_as_adcp_wire` already does for `get_reporting_status`, so "the seller speaks valid AdCP here too" is asserted rather than assumed — a batch this SDK would reject on the wire can no longer pass through the ingest in a test. Refs adcontextprotocol/adcp#7287 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
1 parent 17ac107 commit 011db8f

10 files changed

Lines changed: 1146 additions & 63 deletions

File tree

‎src/adcp/reporting/inline_source.py‎

Lines changed: 35 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -873,20 +873,38 @@ def _control_totals(
873873
# per-cell availability evidence already carries the nuance.
874874
continue
875875
try:
876-
total = sum((_decimal(value) for value in values), Decimal(0))
876+
decimals = [_decimal(value) for value in values]
877877
except (InvalidOperation, TypeError, ValueError):
878878
continue
879-
if total == total.to_integral_value():
879+
if any(not item.is_finite() for item in decimals):
880+
# A NaN or Infinity in a source row has no honest total. Skipping
881+
# the metric leaves the per-cell availability evidence to carry the
882+
# nuance, rather than publishing a control total nobody can check
883+
# against.
884+
continue
885+
total = sum(decimals, Decimal(0))
886+
# The *metric* decides integer vs decimal, not this period's values.
887+
# Deciding per value would flip a money total to "integer" on the days
888+
# it happens to land on a whole number, and a consumer comparing
889+
# totals across periods would see the type change under it.
890+
scaled = any(_scale_of(item) < 0 for item in decimals)
891+
if scaled:
880892
totals.append(
881-
SourceControlTotalV1(name=metric, value=str(int(total)), value_type="integer")
893+
SourceControlTotalV1(name=metric, value=_plain(total), value_type="decimal")
882894
)
883895
else:
884896
totals.append(
885-
SourceControlTotalV1(name=metric, value=_plain(total), value_type="decimal")
897+
SourceControlTotalV1(name=metric, value=str(int(total)), value_type="integer")
886898
)
887899
return totals
888900

889901

902+
def _scale_of(value: Decimal) -> int:
903+
"""The decimal scale, or 0 for a value that has none."""
904+
exponent = value.as_tuple().exponent
905+
return exponent if isinstance(exponent, int) else 0
906+
907+
890908
def _decimal(value: Any) -> Decimal:
891909
if isinstance(value, bool):
892910
raise TypeError("a boolean is not a reportable metric value")
@@ -895,16 +913,25 @@ def _decimal(value: Any) -> Decimal:
895913
if isinstance(value, int):
896914
return Decimal(value)
897915
if isinstance(value, float):
898-
# Through ``repr`` rather than ``Decimal(float)`` so 1.25 stays 1.25
899-
# instead of becoming its full binary expansion.
900-
return Decimal(repr(value))
916+
# A float carries no meaningful scale -- Python renders 10.0 for what
917+
# the wire said was 10 -- so an integral float contributes none. Only a
918+
# genuinely fractional value does, and it goes through ``repr`` rather
919+
# than ``Decimal(float)`` so 1.25 stays 1.25 instead of becoming its
920+
# full binary expansion.
921+
return Decimal(int(value)) if value.is_integer() else Decimal(repr(value))
901922
if isinstance(value, str):
902923
return Decimal(value)
903924
raise TypeError(f"{type(value).__name__} is not a reportable metric value")
904925

905926

906927
def _plain(value: Decimal) -> str:
907-
text = format(value.normalize(), "f")
928+
"""Positional notation, with the source's declared scale preserved.
929+
930+
Deliberately not ``normalize()``: "4.80" and "4.8" are the same number but
931+
different strings, and a money total's scale is information the source
932+
chose to publish. A consumer comparing control totals compares strings.
933+
"""
934+
text = format(value, "f")
908935
return text if text != "-0" else "0"
909936

910937

‎src/adcp/reporting/ledger/__init__.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@
7676
LedgerSnapshot,
7777
ReportingAdjustmentRecord,
7878
ReportingConfiguration,
79+
ReportingDefinitionBinding,
7980
ReportingFinality,
8081
ReportingHealth,
8182
ReportingIssue,
@@ -122,6 +123,7 @@
122123
"ProducerOfferings",
123124
"ReportingAdjustmentRecord",
124125
"ReportingConfiguration",
126+
"ReportingDefinitionBinding",
125127
"ReportingFinality",
126128
"ReportingHealth",
127129
"ReportingIssue",

‎src/adcp/reporting/ledger/models.py‎

Lines changed: 42 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@
2929

3030
__all__ = [
3131
"ConsumerStatusRecord",
32+
"ReportingDefinitionBinding",
3233
"LedgerChange",
3334
"LedgerRecordKind",
3435
"LedgerSnapshot",
@@ -87,6 +88,42 @@ def iso_duration_to_timedelta(value: str) -> timedelta:
8788
)
8889

8990

91+
@dataclass(frozen=True)
92+
class ReportingDefinitionBinding:
93+
"""The content-addressed report definition an obligation reports against.
94+
95+
Core's wire records are self-describing: a retained revision names the
96+
exact definition and row schema it was produced under, by URI *and* digest,
97+
so a consumer reading it years later can verify it is reading what it
98+
thinks it is. Without this, ``report_definition_id`` is just a string two
99+
parties hope still means the same thing.
100+
101+
Optional on :class:`ReportingConfiguration` only so an in-process pilot can
102+
get moving; a seller advertising ``reporting.core`` must supply it, because
103+
:class:`~adcp.reporting.ledger.status.ReportingStatusHandler` cannot emit a
104+
schema-valid ``reporting-revision`` record without it.
105+
"""
106+
107+
report_definition_uri: str
108+
report_definition_sha256: str
109+
schema_version: str
110+
schema_uri: str
111+
schema_sha256: str
112+
schema_dialect: str = "https://json-schema.org/draft/2020-12/schema"
113+
schema_ref_policy: str = "local_fragment_only"
114+
115+
def to_wire(self) -> dict[str, Any]:
116+
return {
117+
"report_definition_uri": self.report_definition_uri,
118+
"report_definition_sha256": self.report_definition_sha256,
119+
"schema_version": self.schema_version,
120+
"schema_uri": self.schema_uri,
121+
"schema_sha256": self.schema_sha256,
122+
"schema_dialect": self.schema_dialect,
123+
"schema_ref_policy": self.schema_ref_policy,
124+
}
125+
126+
90127
@dataclass(frozen=True)
91128
class ReportingScheduleSpec:
92129
"""The clock a reporting configuration creates.
@@ -176,7 +213,9 @@ def derive_period(
176213
"full boundary; a partial first period would understate delivery"
177214
)
178215
return ReportingPeriodBoundary(
179-
period_key=f"{start.strftime('%Y-%m-%dT%H:%M:%SZ')}/{schedule.period_duration}",
216+
# No "/": a period key travels into the source slice request, whose
217+
# identifier pattern is [A-Za-z0-9_.:-].
218+
period_key=f"{start.strftime('%Y-%m-%dT%H:%M:%SZ')}_{schedule.period_duration}",
180219
start=start,
181220
end=end,
182221
source_timezone=zone_name,
@@ -235,6 +274,7 @@ class ReportingConfiguration:
235274
media_buy_ids: tuple[str, ...] = ()
236275
automated_recovery_window: timedelta = timedelta(hours=6)
237276
status_retention_days: int = 400
277+
definition: ReportingDefinitionBinding | None = None
238278

239279
@property
240280
def generation_key(self) -> tuple[str, int]:
@@ -266,6 +306,7 @@ class ReportingObligationRecord:
266306
schedule: ReportingScheduleSpec
267307
coverage_status: Literal["full", "partial", "none", "unknown"] = "full"
268308
package_ids: tuple[str, ...] = ()
309+
definition: ReportingDefinitionBinding | None = None
269310
created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
270311

271312
def __post_init__(self) -> None:

‎src/adcp/reporting/ledger/pg.py‎

Lines changed: 29 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,7 @@
8080
LedgerSnapshot,
8181
ReportingAdjustmentRecord,
8282
ReportingConfiguration,
83+
ReportingDefinitionBinding,
8384
ReportingObligationRecord,
8485
ReportingPeriodBoundary,
8586
ReportingRevisionRecord,
@@ -188,8 +189,10 @@ async def put_configuration(self, configuration: ReportingConfiguration) -> None
188189
" (delivery_config_id, delivery_config_version, account_id,"
189190
" report_definition_id, reporting_profile, feed_purpose, required_finality,"
190191
" account_timezone, schedule, media_buy_ids, activated_at, deactivated_at,"
191-
" automated_recovery_seconds, status_retention_days, content_sha256)"
192-
" VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s::jsonb, %s::jsonb, %s, %s, %s, %s, %s)"
192+
" automated_recovery_seconds, status_retention_days, definition,"
193+
" content_sha256)"
194+
" VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s::jsonb, %s::jsonb, %s, %s, %s, %s,"
195+
" %s::jsonb, %s)"
193196
" ON CONFLICT (delivery_config_id, delivery_config_version) DO NOTHING",
194197
(
195198
configuration.delivery_config_id,
@@ -206,6 +209,7 @@ async def put_configuration(self, configuration: ReportingConfiguration) -> None
206209
configuration.deactivated_at,
207210
configuration.automated_recovery_window.total_seconds(),
208211
configuration.status_retention_days,
212+
_json(payload["definition"]) if payload["definition"] else None,
209213
digest,
210214
),
211215
)
@@ -223,7 +227,7 @@ async def list_configurations(
223227
"SELECT delivery_config_id, delivery_config_version, account_id," # noqa: S608 # nosec B608
224228
" report_definition_id, reporting_profile, feed_purpose, required_finality,"
225229
" account_timezone, schedule, media_buy_ids, activated_at, deactivated_at,"
226-
" automated_recovery_seconds, status_retention_days"
230+
" automated_recovery_seconds, status_retention_days, definition"
227231
" FROM reporting_configurations"
228232
f" WHERE account_id = %s{clause}" # noqa: S608 — clause is a literal
229233
" ORDER BY delivery_config_id, delivery_config_version",
@@ -247,9 +251,9 @@ async def commit_obligation(
247251
" feed_purpose, period_key, period_start, period_end, source_timezone,"
248252
" expected_at, scope_resolved_at, automated_recovery_deadline_at,"
249253
" required_finality, coverage_status, media_buy_ids, package_ids,"
250-
" schedule, created_at)"
254+
" schedule, definition, created_at)"
251255
" VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s,"
252-
" %s::jsonb, %s::jsonb, %s::jsonb, %s)"
256+
" %s::jsonb, %s::jsonb, %s::jsonb, %s::jsonb, %s)"
253257
" ON CONFLICT DO NOTHING"
254258
" RETURNING reporting_obligation_id",
255259
(
@@ -272,6 +276,11 @@ async def commit_obligation(
272276
_json(sorted(obligation.media_buy_ids)),
273277
_json(sorted(obligation.package_ids)),
274278
_json(_schedule_payload(obligation.schedule)),
279+
(
280+
_json(_definition_payload(obligation.definition))
281+
if obligation.definition
282+
else None
283+
),
275284
obligation.created_at,
276285
),
277286
)
@@ -982,7 +991,7 @@ def _translate_integrity_error(error: Exception) -> LedgerConflictError:
982991
" report_definition_id, reporting_profile, feed_purpose, period_key, period_start,"
983992
" period_end, source_timezone, expected_at, scope_resolved_at,"
984993
" automated_recovery_deadline_at, required_finality, coverage_status, media_buy_ids,"
985-
" package_ids, schedule, created_at"
994+
" package_ids, schedule, definition, created_at"
986995
)
987996

988997
_REVISION_COLUMNS = (
@@ -1022,6 +1031,16 @@ def _schedule_payload(schedule: ReportingScheduleSpec) -> dict[str, Any]:
10221031
}
10231032

10241033

1034+
def _definition_payload(
1035+
definition: ReportingDefinitionBinding | None,
1036+
) -> dict[str, Any] | None:
1037+
return definition.to_wire() if definition is not None else None
1038+
1039+
1040+
def _definition_from_payload(payload: dict[str, Any] | None) -> ReportingDefinitionBinding | None:
1041+
return ReportingDefinitionBinding(**payload) if payload else None
1042+
1043+
10251044
def _schedule_from_payload(payload: dict[str, Any]) -> ReportingScheduleSpec:
10261045
anchor = payload.get("period_anchor")
10271046
return ReportingScheduleSpec(
@@ -1043,6 +1062,7 @@ def _configuration_payload(configuration: ReportingConfiguration) -> dict[str, A
10431062
"account_timezone": configuration.account_timezone,
10441063
"media_buy_ids": sorted(configuration.media_buy_ids),
10451064
"schedule": _schedule_payload(configuration.schedule),
1065+
"definition": _definition_payload(configuration.definition),
10461066
}
10471067

10481068

@@ -1062,6 +1082,7 @@ def _configuration_from_row(row: Sequence[Any]) -> ReportingConfiguration:
10621082
deactivated_at=_utc(row[11]) if row[11] else None,
10631083
automated_recovery_window=timedelta(seconds=float(row[12])),
10641084
status_retention_days=row[13],
1085+
definition=_definition_from_payload(row[14]),
10651086
)
10661087

10671088

@@ -1088,7 +1109,8 @@ def _obligation_from_row(row: Sequence[Any]) -> ReportingObligationRecord:
10881109
media_buy_ids=tuple(row[16] or ()),
10891110
package_ids=tuple(row[17] or ()),
10901111
schedule=_schedule_from_payload(row[18]),
1091-
created_at=_utc(row[19]),
1112+
definition=_definition_from_payload(row[19]),
1113+
created_at=_utc(row[20]),
10921114
)
10931115

10941116

‎src/adcp/reporting/ledger/producer.py‎

Lines changed: 32 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -270,6 +270,7 @@ async def _close_elapsed_periods(
270270
boundary.expected_at + configuration.automated_recovery_window
271271
),
272272
schedule=configuration.schedule,
273+
definition=configuration.definition,
273274
created_at=now,
274275
)
275276
stored = await self._store.commit_obligation(obligation)
@@ -356,31 +357,33 @@ async def acquire_obligation(
356357
configuration: ReportingConfiguration,
357358
obligation: ReportingObligationRecord,
358359
*,
360+
restate: bool = False,
359361
turn: WorkerTurn | None = None,
360362
now: datetime | None = None,
361363
) -> ReportingRevisionRecord | None:
362364
"""Drive one obligation from its source and commit what comes back.
363365
364366
Returns the committed revision, or ``None`` when the source is not ready
365367
or the obligation is already satisfied.
368+
369+
``restate`` asks for a *new observation* of an already-satisfied
370+
snapshot obligation. Without it a satisfied obligation is left alone,
371+
because re-reading a settled period on every worker turn would burn
372+
upstream quota to republish bytes nobody asked for.
366373
"""
367374
turn = turn or WorkerTurn()
368375
now = now or self._clock()
369376
revisions = await self._store.list_revisions(
370377
account_id=obligation.account_id,
371378
reporting_obligation_id=obligation.reporting_obligation_id,
372379
)
373-
if any(
374-
item.finality == "official"
375-
or (obligation.required_finality == "snapshot" and item.readable)
376-
for item in revisions
377-
):
378-
# Officials are terminal; a satisfied snapshot obligation restates
379-
# only when the caller asks for it explicitly.
380-
if obligation.required_finality == "snapshot" or any(
381-
item.finality == "official" for item in revisions
382-
):
383-
return None
380+
if any(item.finality == "official" for item in revisions):
381+
# An official close is terminal. A later source correction is an
382+
# adjustment, never another acquisition.
383+
return None
384+
satisfied = any(item.readable for item in revisions)
385+
if satisfied and not restate:
386+
return None
384387

385388
finality = obligation.required_finality
386389
offering_id = self._offerings.offering_for(finality)
@@ -390,7 +393,9 @@ async def acquire_obligation(
390393
f"this producer declares no source offering for {finality} reporting",
391394
)
392395

393-
request = self._build_slice(configuration, obligation, offering_id, now=now)
396+
request = self._build_slice(
397+
configuration, obligation, offering_id, now=now, observation=len(revisions)
398+
)
394399
cancel = asyncio.Event()
395400
try:
396401
result = await asyncio.wait_for(
@@ -558,12 +563,21 @@ def _build_slice(
558563
offering_id: str,
559564
*,
560565
now: datetime,
566+
observation: int = 0,
561567
) -> ReportingSourceSliceRequestV1:
562568
"""Freeze one slice request from the obligation.
563569
564-
``source_execution_key`` is derived from the obligation plus the
565-
offering, so a retried acquisition of the same obligation replays the
566-
same sealed publication rather than minting a second one.
570+
``source_execution_key`` is derived from the obligation, the offering,
571+
and the **observation ordinal** -- the number of revisions already
572+
committed for this obligation.
573+
574+
That last term is what makes both behaviors correct at once. A *retry*
575+
of a failed acquisition commits nothing, so the ordinal is unchanged,
576+
the key is unchanged, and the source replays its sealed publication
577+
rather than minting a second one. A *restatement* follows a committed
578+
revision, so the ordinal advances and the source is genuinely re-read
579+
as a new immutable observation. The ordinal comes from durable state,
580+
not from the clock, so neither behavior depends on wall time.
567581
"""
568582
constituents: list[ReportingConstituent] = [
569583
MediaBuyConstituentV1(
@@ -582,7 +596,9 @@ def _build_slice(
582596
source_execution_key = (
583597
"rse-"
584598
+ hashlib.sha256(
585-
canonical_json_utf8_v1([obligation.reporting_obligation_id, offering_id])
599+
canonical_json_utf8_v1(
600+
[obligation.reporting_obligation_id, offering_id, observation]
601+
)
586602
).hexdigest()[:40]
587603
)
588604
publication_class: ReportingPublicationClass = (

0 commit comments

Comments
 (0)