From 353bf3de71bac280df3cdd94e265d425871c80fb Mon Sep 17 00:00:00 2001 From: rachitm022 Date: Thu, 19 Nov 2026 16:46:15 +0530 Subject: [PATCH] fix(reporting): align source timezone days to local midnight --- src/adcp/reporting/ledger/consumer_status.py | 12 +- src/adcp/reporting/ledger/models.py | 30 ++-- src/adcp/reporting/production/offerings.py | 19 ++- .../reporting/_production_support.py | 8 +- ...test_reporting_production_configuration.py | 82 +++++++++- .../test_reporting_projection_schedule.py | 145 +++++++++++++++++- 6 files changed, 263 insertions(+), 33 deletions(-) diff --git a/src/adcp/reporting/ledger/consumer_status.py b/src/adcp/reporting/ledger/consumer_status.py index 2e790a7bc0..5add048a43 100644 --- a/src/adcp/reporting/ledger/consumer_status.py +++ b/src/adcp/reporting/ledger/consumer_status.py @@ -574,9 +574,7 @@ def validate_consumer_status_timing( record: ConsumerStatusRecord, generation: ReportingConfiguration, *, as_of: datetime ) -> None: """Validate a statement's derived calendar and observation at the locked boundary.""" - from zoneinfo import ZoneInfo - - from adcp.reporting.ledger.models import derive_period, iso_duration_to_timedelta + from adcp.reporting.ledger.models import _schedule_clock, derive_period stamps = ( record.period_start, @@ -602,12 +600,8 @@ def validate_consumer_status_timing( raise LedgerConflictError( "INVALID_STATUS_PERIOD", "status timezone differs from the accepted schedule" ) - zone = ZoneInfo(zone_name) - anchor = generation.schedule.period_anchor or datetime(1970, 1, 1, tzinfo=timezone.utc) - delta = record.period_start.astimezone(zone).replace(tzinfo=None) - anchor.astimezone( - zone - ).replace(tzinfo=None) - duration = iso_duration_to_timedelta(generation.schedule.period_duration) + zone, duration, anchor = _schedule_clock(generation.schedule, generation.account_timezone) + delta = record.period_start.astimezone(zone).replace(tzinfo=None) - anchor if duration <= timedelta(0) or delta % duration: raise LedgerConflictError( "INVALID_STATUS_PERIOD", "status period is not a scheduled boundary" diff --git a/src/adcp/reporting/ledger/models.py b/src/adcp/reporting/ledger/models.py index a0437e7a0e..a27559724a 100644 --- a/src/adcp/reporting/ledger/models.py +++ b/src/adcp/reporting/ledger/models.py @@ -205,7 +205,7 @@ class ReportingScheduleSpec: period_duration: str delivery_sla: str - alignment: Literal["utc", "account_timezone", "custom_timezone"] = "utc" + alignment: Literal["utc", "account_timezone", "custom_timezone", "source_timezone"] = "utc" period_timezone: str | None = None period_anchor: datetime | None = None @@ -214,6 +214,10 @@ def timezone_name(self, account_timezone: str) -> str: return "UTC" if self.alignment == "account_timezone": return account_timezone + if self.alignment == "source_timezone": + if not self.period_timezone: + raise ValueError("source_timezone alignment requires period_timezone") + return self.period_timezone if not self.period_timezone: raise ValueError("custom_timezone alignment requires period_timezone") return self.period_timezone @@ -243,12 +247,18 @@ def _schedule_clock( duration = iso_duration_to_timedelta(schedule.period_duration) if duration <= timedelta(0): raise ValueError("period_duration must be positive") - anchor = ( - _utc(schedule.period_anchor) - if schedule.period_anchor is not None - else datetime(1970, 1, 1, tzinfo=timezone.utc) - ) - return zone, duration, anchor.astimezone(zone).replace(tzinfo=None) + if schedule.alignment == "source_timezone": + if schedule.period_anchor is not None: + raise ValueError("source_timezone alignment does not accept period_anchor") + anchor = datetime(1970, 1, 1) + else: + instant = ( + _utc(schedule.period_anchor) + if schedule.period_anchor is not None + else datetime(1970, 1, 1, tzinfo=timezone.utc) + ) + anchor = instant.astimezone(zone).replace(tzinfo=None) + return zone, duration, anchor def _period_instants( @@ -277,9 +287,9 @@ def derive_period( evidence that nothing happened. That only works if the derivation is identical, so it lives here rather than in each side's handler. - Periods are anchored at the Unix epoch in the schedule's timezone (or at an - explicit ``period_anchor`` for billing-cycle alignment), which is what makes - "the next full boundary" unambiguous. A configuration activated mid-period + Source-timezone periods use local midnight as their civil-day origin. + Other periods use the Unix epoch's local clock or an explicit anchor. + A configuration activated mid-period begins at the next boundary -- a partial first period would be reported as complete and understate delivery. """ diff --git a/src/adcp/reporting/production/offerings.py b/src/adcp/reporting/production/offerings.py index 8ea28e5151..c1951f39f5 100644 --- a/src/adcp/reporting/production/offerings.py +++ b/src/adcp/reporting/production/offerings.py @@ -229,6 +229,7 @@ def check_source(self, *, effective: bool = False) -> ReportingSourceCapabilitie raise failure("UNSUPPORTED_VERIFICATION") if ( schedule["alignment"] == "source_timezone" + and source_offering.source_timezone is not None and schedule.get("period_timezone") != source_offering.source_timezone ): raise failure("UNSUPPORTED_VERIFICATION") @@ -269,15 +270,16 @@ def configuration_schedule(self, configuration: ReportingConfiguration) -> dict[ offered = self.wire()["schedule"] schedule = configuration.schedule alignment = offered["alignment"] - expected_alignment = ( - alignment if alignment in {"utc", "account_timezone"} else "custom_timezone" - ) + expected_alignment = alignment if alignment != "billing_cycle" else "custom_timezone" zone, duration, anchor = _schedule_clock(schedule, configuration.account_timezone) if ( schedule.alignment != expected_alignment or schedule.period_duration != offered["period_duration"] or schedule.delivery_sla != offered["delivery_sla"] - or (alignment != "billing_cycle" and (anchor - datetime(1970, 1, 1)) % duration) + or ( + alignment not in {"billing_cycle", "source_timezone"} + and (anchor - datetime(1970, 1, 1)) % duration + ) or (alignment == "billing_cycle" and schedule.period_anchor is None) ): raise failure("BINDING_MISMATCH") @@ -302,8 +304,13 @@ def configuration_schedule(self, configuration: ReportingConfiguration) -> dict[ raise failure("BINDING_MISMATCH") if ( alignment == "source_timezone" - and zone.key - != self.check_source(effective=True).offering(self.source_offering_id).source_timezone + and ( + source_zone := self.check_source(effective=True) + .offering(self.source_offering_id) + .source_timezone + ) + is not None + and zone.key != source_zone ): raise failure("BINDING_MISMATCH") return result diff --git a/tests/conformance/reporting/_production_support.py b/tests/conformance/reporting/_production_support.py index 6bd44089d8..00e4b3f11c 100644 --- a/tests/conformance/reporting/_production_support.py +++ b/tests/conformance/reporting/_production_support.py @@ -393,6 +393,7 @@ async def production_harness( adcp_version=None, source_registry_factory=None, service_factory=None, + offering_schedule=None, ): from contextlib import AsyncExitStack @@ -585,11 +586,8 @@ async def production_harness( "report_definition_uri": key.definition.report_definition_uri, "report_definition_sha256": key.definition.report_definition_sha256, "reporting_profile": profile, - "schedule": { - "period_duration": "PT1H", - "alignment": "utc", - "delivery_sla": "PT1H", - }, + "schedule": offering_schedule + or {"period_duration": "PT1H", "alignment": "utc", "delivery_sla": "PT1H"}, "supported_finality": [config.required_finality], "reconciliation_mode": binding.reconciliation_mode, "method": writer.delivery_methods[0].wire(), diff --git a/tests/conformance/reporting/test_reporting_production_configuration.py b/tests/conformance/reporting/test_reporting_production_configuration.py index dcfafb0296..1fbb2fe6c2 100644 --- a/tests/conformance/reporting/test_reporting_production_configuration.py +++ b/tests/conformance/reporting/test_reporting_production_configuration.py @@ -4,19 +4,25 @@ import json import sqlite3 from dataclasses import replace -from datetime import timedelta, timezone +from datetime import datetime, timedelta, timezone +from typing import Any import pytest +from adcp.reporting.ledger import ReportingScheduleSpec from adcp.reporting.ledger.notification_models import ReportingNotificationError from adcp.reporting.materializer.contracts import ReportingWriterError, binding_fingerprint from adcp.reporting.materializer.work import ReportingMaterializerLease from adcp.reporting.production.configuration import ReportingConfigurationAdmission +from adcp.reporting.source import ( + ReportingSourceCapabilitiesV1, + reporting_source_capabilities_sha256_v1, +) from adcp.validation.schema_loader import get_named_validator from ._feed_support import feed_request, walk from ._generation_support import END -from ._production_support import production_harness +from ._production_support import Source, production_harness from ._production_transport import MountedProduction from ._receipt_transport import error_code from .test_reporting_production_bindings import source_documents @@ -42,6 +48,78 @@ def wire_configuration(h): } +@pytest.mark.parametrize( + "policy,offered_zone,accepted", + [ + ("account_resolved", None, True), + ("fixed", "America/Los_Angeles", False), + ], +) +async def test_source_timezone_admission_uses_the_resolved_network_zone( + policy, offered_zone, accepted, tmp_path +): + class AccountResolvedSource(Source): + def __init__(self, *args: Any, **kwargs: Any) -> None: + super().__init__(*args, **kwargs) + raw = self.capabilities.model_dump(mode="json", exclude_none=True) + raw["offerings"][0].pop("source_timezone") + raw["capabilities_sha256"] = reporting_source_capabilities_sha256_v1(raw) + self.capabilities = ReportingSourceCapabilitiesV1.model_validate(raw) + + offered_schedule = { + "period_duration": "P1D", + "delivery_sla": "PT1H", + "alignment": "source_timezone", + "period_timezone_policy": policy, + } + if offered_zone is not None: + offered_schedule["period_timezone"] = offered_zone + async with production_harness( + "memory", + tmp_path / "destination.sqlite", + count=0, + source_factory=AccountResolvedSource, + offering_schedule=offered_schedule, + ) as h: + installed = h.production.offerings[0] + source = installed.producer._source + assert source.capabilities.scope == "effective_account" + assert source.capabilities.offering(installed.source_offering_id).source_timezone is None + config = replace( + h.item.config, + delivery_config_version=2, + account_timezone="UTC", + activated_at=datetime(2026, 3, 8, 5, tzinfo=timezone.utc), + schedule=ReportingScheduleSpec("P1D", "PT1H", "source_timezone", "America/New_York"), + ) + binding = replace(h.item.binding, generation_key=config.generation_key) + source.bind_generation(config) + h.item.writer.grant(binding) + await h.production.activate(account_id=config.account_id) + if accepted: + await h.store.admit_production_configuration( + config, binding, offering_id=installed.offering_id + ) + assert installed.configuration_schedule(config) == { + "period_duration": "P1D", + "delivery_sla": "PT1H", + "alignment": "source_timezone", + "period_timezone": "America/New_York", + } + assert config in await h.store.list_configurations( + caller=binding.principal, delivery_config_ids=[config.delivery_config_id] + ) + else: + with pytest.raises(ReportingWriterError) as denied: + await h.store.admit_production_configuration( + config, binding, offering_id=installed.offering_id + ) + assert denied.value.failure.code == "BINDING_MISMATCH" + assert config not in await h.store.list_configurations( + caller=binding.principal, delivery_config_ids=[config.delivery_config_id] + ) + + def state_for(h, configuration): ids = list(h.item.config.media_buy_ids) coverage = { diff --git a/tests/conformance/reporting/test_reporting_projection_schedule.py b/tests/conformance/reporting/test_reporting_projection_schedule.py index d18671450b..dfb719d7f4 100644 --- a/tests/conformance/reporting/test_reporting_projection_schedule.py +++ b/tests/conformance/reporting/test_reporting_projection_schedule.py @@ -3,11 +3,19 @@ from dataclasses import replace from datetime import datetime, timedelta, timezone from itertools import islice +from zoneinfo import ZoneInfo import pytest -from adcp.reporting.ledger import ProducerOfferings, ReportingProducer, ReportingScheduleSpec +from adcp.reporting.ledger import ( + ConsumerStatusRecord, + ProducerOfferings, + ReportingProducer, + ReportingScheduleSpec, +) from adcp.reporting.ledger import ReportingStatusCaller as OwnershipCaller +from adcp.reporting.ledger.consumer_status import validate_consumer_status_timing +from adcp.reporting.ledger.producer import _source_local_date from adcp.reporting.ledger.schedule import committed_periods, next_reporting_expectation from adcp.reporting.ledger.status import ReportingStatusCaller, ReportingStatusHandler from adcp.types import GetReportingStatusResponse @@ -152,6 +160,141 @@ def test_civil_days_across_dst_preserve_the_captured_timezone_and_sla(date, hour assert next_reporting_expectation((config,), (), as_of=first.expected_at) > first.expected_at +@pytest.mark.parametrize( + "zone_name,local_date,start,end", + [ + ( + "America/New_York", + "2026-03-08", + "2026-03-08T05:00:00+00:00", + "2026-03-09T04:00:00+00:00", + ), + ( + "America/New_York", + "2026-11-01", + "2026-11-01T04:00:00+00:00", + "2026-11-02T05:00:00+00:00", + ), + ("Asia/Kolkata", "2026-09-15", "2026-09-14T18:30:00+00:00", "2026-09-15T18:30:00+00:00"), + ], +) +def test_source_timezone_daily_periods_are_local_midnights_with_stable_identity( + zone_name, local_date, start, end +): + first_start = datetime.fromisoformat(start) + first_end = datetime.fromisoformat(end) + config = replace( + configuration(), + account_timezone="UTC", + activated_at=first_start, + deactivated_at=first_end, + schedule=ReportingScheduleSpec("P1D", "PT1H", "source_timezone", zone_name), + ) + first = next(committed_periods(config)) + assert first.start == first_start + assert first.end == first_end + assert first.start.astimezone(ZoneInfo(zone_name)).date().isoformat() == local_date + assert _source_local_date(first.start, first.source_timezone) == local_date + assert first.source_timezone == zone_name + assert first.period_key == f"{first_start.strftime('%Y-%m-%dT%H:%M:%SZ')}_P1D" + assert first.expected_at == first_end + timedelta(hours=1) + assert next(committed_periods(config)).period_key == first.period_key + assert next_reporting_expectation((config,), (), as_of=first_start) == first.expected_at + + +async def test_source_timezone_period_close_retry_keeps_the_same_identity(schedules): + h = schedules + start = datetime(2026, 3, 8, 5, tzinfo=timezone.utc) + end = datetime(2026, 3, 9, 4, tzinfo=timezone.utc) + config = replace( + configuration(), + activated_at=start, + deactivated_at=end, + schedule=ReportingScheduleSpec("P1D", "PT1H", "source_timezone", "America/New_York"), + ) + h.clock.now = end + timedelta(hours=1) + await h.store.put_configuration(config) + producer = ReportingProducer( + source=UncalledSource(), offerings=ProducerOfferings(), store=h.store + ) + first = await producer.close_elapsed_periods(config, now=h.clock()) + assert len(first) == 1 + assert first[0].period == next(committed_periods(config)) + assert await producer.close_elapsed_periods(config, now=h.clock()) == [] + + +@pytest.mark.parametrize( + "alignment,zone_name", + [ + ("utc", None), + ("account_timezone", None), + ("custom_timezone", "America/New_York"), + ], +) +def test_captured_clock_phase_is_unchanged_for_existing_alignments(alignment, zone_name): + schedule = ReportingScheduleSpec("P1D", "PT1H", alignment, zone_name) + config = replace( + configuration(), + account_timezone="America/New_York", + activated_at=datetime(2026, 3, 8, tzinfo=timezone.utc), + deactivated_at=datetime(2026, 3, 11, tzinfo=timezone.utc), + schedule=schedule, + ) + first = next(committed_periods(config)) + assert first.start == datetime(2026, 3, 8, tzinfo=timezone.utc) + assert first.end == datetime( + 2026, + 3, + 9 if alignment == "utc" else 8, + 0 if alignment == "utc" else 23, + tzinfo=timezone.utc, + ) + + +def test_consumer_status_uses_the_source_timezone_calendar(): + start = datetime(2026, 3, 8, 5, tzinfo=timezone.utc) + config = replace( + configuration(), + activated_at=start, + deactivated_at=None, + schedule=ReportingScheduleSpec("P1D", "PT1H", "source_timezone", "America/New_York"), + ) + period = next(committed_periods(config)) + statement = ConsumerStatusRecord( + reporting_status_id="status_source_day", + account_id=config.account_id, + consumer_id=config.consumer_id, + delivery_config_id=config.delivery_config_id, + delivery_config_version=config.delivery_config_version, + report_definition_id=config.report_definition_id, + period_start=period.start, + period_end=period.end, + period_source_timezone=period.source_timezone, + consumer_status="obligation_missing", + status_as_of=period.expected_at, + recorded_at=period.expected_at, + ) + validate_consumer_status_timing(statement, config, as_of=period.expected_at) + + +@pytest.mark.parametrize( + "schedule", + [ + ReportingScheduleSpec("P1D", "PT1H", "source_timezone"), + ReportingScheduleSpec( + "P1D", + "PT1H", + "source_timezone", + "America/New_York", + datetime(2026, 1, 1, tzinfo=timezone.utc), + ), + ], +) +def test_source_timezone_schedule_requires_a_resolved_zone_and_no_anchor(schedule): + with pytest.raises(ValueError): + next(committed_periods(replace(configuration(), schedule=schedule))) + + @pytest.mark.parametrize("duration", ["PT1H", "PT10M"]) def test_nonexistent_civil_slots_are_skipped_without_duplicate_or_reordered_periods(duration): start = datetime(2026, 3, 8, 5, tzinfo=timezone.utc)