Skip to content

Commit dfffa68

Browse files
bokelleyclaude
andcommitted
fix(reporting): model package exclusions and membership edits as the reference model does
Two disagreements with the spec's reference model, found by its differential generator (adcontextprotocol/adcp 8ee1bfa2) and fixed the same way in the TypeScript SDK (adcontextprotocol/adcp-client#3620): - A package_ids exception was modelled as a resolution change: it took the package out of resolution and started a regime, so a window naming every package of a buy reset the E a later resolution inherited. It now removes a period only when one entry covering the period start names every package resolving the offering that is owed the period, and never splits a regime. - One excluded_by_buyer entry put every version under in-place membership. Only the versions whose span an entry overlaps are now; another version keeps its own account_ids and exclude_account_ids. The three minimized differential scenarios are vendored from the TypeScript SDK and pass. explain writes the before_package_added facts (packages_added_at), sentence and buy facts (packages[].added_at) exactly as the TypeScript SDK does, and reports a period a package_ids entry removes under that entry's reason. A test pins the billing stub at an account-timezone cutover, which both SDKs owe per the cutover text where the 8ee1bfa2 reference model emits none (fixed in the spec for beta.5). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 2c8548a commit dfffa68

6 files changed

Lines changed: 576 additions & 140 deletions

File tree

‎docs/reporting-subscriptions-coverage.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -125,7 +125,7 @@ A period that ends at or before the buy's `confirmed_at` is not owed (`before_co
125125

126126
A package added to a confirmed buy carries `added_at` on `get_media_buys` (3.3.0-beta.4), and `added_at` is that package's own `confirmed_at`. Each package is owed from the later of the buy's `confirmed_at` and its `added_at` (`confirmed_at` alone when `added_at` is absent: the package was part of the buy at confirmation). The buy owes a period of an offering when the period ends after that instant for at least one package resolving the offering. So the period containing `added_at` is owed in full, earlier periods are owed only through packages the buy already had, and adding a package is never a cutover. When every package resolving the offering was added after the period ended, the reason is `before_package_added`.
127127

128-
The package also resolves at the later of the version's `accepted_at` and its own `confirmed_at`, among the offerings available then. A `package_ids` exception removes a period when it names every package resolving the offering that is owed that period, so packages added and removed compose: a package keeps the buy covered from its `added_at` until an entry naming it takes it out.
128+
The package also resolves at the later of the version's `accepted_at` and its own `confirmed_at`, among the offerings available then. A `package_ids` exception removes a period when it names every package resolving the offering that is owed that period, so packages added and removed compose: a package keeps the buy covered from its `added_at` until an entry naming it takes it out. A `package_ids` exception never changes resolution, so it never starts a cutover.
129129

130130
`SubscriptionBuy.from_media_buy` reads `packages[].added_at` into `SubscriptionBuyPackage.added_at`, and `SubscriptionBuy.package_confirmed_at(package_id)` is the instant it is owed from.
131131

@@ -157,6 +157,8 @@ A timezone change takes effect at its `effective_at`, and each zone owes only it
157157

158158
When a cutover hands a billing feed to a schedule with no boundary at E, the stretch from E to the first incoming boundary is owed as one stub period. Its obligation carries `stub: true` (`OwedSubscriptionPeriod.stub`, `ReportingObligationRecord.stub`). Pacing and analytics feeds leave that stretch unowed.
159159

160+
This applies at every cutover, an account-timezone change included, as the `cutover` text says. The reference model at adcontextprotocol/adcp 8ee1bfa2 emits no stub at a timezone cutover; the spec fixes that for beta.5, and both SDKs follow the text.
161+
160162
### Sticky resolution
161163

162164
A package resolves once, when its (buy, version) pair first does: at the later of the version's `accepted_at` and the package's own `confirmed_at` (the buy's, or its `added_at` when later), among the offerings available then. An offering published later never re-resolves it. A resolved offering's `withdrawn_at` is the one change: the package re-resolves among the offerings available then, as a cutover.

‎docs/reporting-subscriptions-seller.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ The reference seller (`python -m adcp reference-seller reporting`) is a complete
5353

5454
- **Admission under `max_accounts`.** Candidates are ordered by `authorization.authorized_at`, then `account_id` in byte order, and an admitted account keeps its slot. A waiting candidate carries a `capacity` exception.
5555
- **Several feeds per purpose.** A caller may hold several pacing or analytics subscriptions for one account. Where two resolve the same offering for a package, the lowest `subscription_id` owes it and the other records an `overridden` exception naming the `package_ids`. Billing stays one per account at a scope level.
56-
- **Membership in place.** Membership edits (`account_ids`, `exclude_account_ids`) keep the version. A removed account stays listed, `excluded`, with an `excluded_by_buyer` entry from the cutover. An added account gets a closed entry covering the time before it joined.
56+
- **Membership in place.** Membership edits (`account_ids`, `exclude_account_ids`) keep the version. A removed account stays listed, `excluded`, with an `excluded_by_buyer` entry from the cutover. An added account gets a closed entry covering the time before it joined. On the buyer side, `excluded_by_buyer` entries decide membership only for the versions whose span they overlap; any other version keeps its own lists.
5757
- **`destination_overrides`.** An account named by an override, by `account_ids` or `operator_domains`, resolves against the override's destination method. Its owed sets carry the override as the version's `destination`, so `bind_managed_generation` binds and checks the override's `path_template`.
5858
- **Bounded readback.** `prior_versions` lists the 16 newest inline, and the account lists 1,000, each with a total count. `get_principal` `reporting_subscription_page` pages the rest from the engine's state.
5959
- **Partial grants.** A grant that keeps the account covered refuses a task it does not list with `SCOPE_INSUFFICIENT`.

‎src/adcp/reporting/subscriptions/coverage.py‎

Lines changed: 74 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -421,8 +421,9 @@ class SubscriptionException:
421421
#: ``offering_id``); ``None`` is every offering.
422422
offering_id: str | None = None
423423
#: A package-level entry (``package_ids``, with ``media_buy_id``): it removes
424-
#: those packages from the buy's coverage while open, never periods. An
425-
#: ``overridden`` entry names the packages a lower ``subscription_id`` owes.
424+
#: a period only when it names every package resolving the offering that is
425+
#: owed the period, and never changes resolution. An ``overridden`` entry
426+
#: names the packages a lower ``subscription_id`` owes.
426427
package_ids: tuple[str, ...] = ()
427428

428429
def __post_init__(self) -> None:
@@ -441,6 +442,26 @@ def removes_package(self, at: datetime, media_buy_id: str, package_id: str) -> b
441442
and (self.until is None or at < self.until)
442443
)
443444

445+
def removes_packages(
446+
self, start: datetime, media_buy_id: str, offering_id: str, owing: Iterable[str]
447+
) -> bool:
448+
"""Whether this package-level entry removes a period starting at ``start``.
449+
450+
3.3.0-beta.4 (the reference model's ``excepted``): it covers the start,
451+
applies to the buy and offering, and names every package resolving the
452+
offering that is owed the period (``owing``, never empty).
453+
"""
454+
owing = tuple(owing)
455+
return (
456+
bool(self.package_ids)
457+
and bool(owing)
458+
and (self.media_buy_id is None or self.media_buy_id == media_buy_id)
459+
and (self.offering_id is None or self.offering_id == offering_id)
460+
and self.from_ <= start
461+
and (self.until is None or start < self.until)
462+
and all(package_id in self.package_ids for package_id in owing)
463+
)
464+
444465
def removes(self, start: datetime, media_buy_id: str, offering_id: str | None = None) -> bool:
445466
if self.package_ids:
446467
return False # removes packages from coverage, not periods
@@ -459,8 +480,8 @@ def subscription_exceptions(
459480
460481
An entry naming ``package_ids`` (``offering_unsupported``, or
461482
``overridden`` by a lower ``subscription_id`` resolving the same offering,
462-
adcp#8619) removes those packages from the buy's coverage while it is
463-
open, not periods.
483+
adcp#8619) removes a period whose start it covers only when it names every
484+
package resolving the offering that is owed the period (3.3.0-beta.4).
464485
"""
465486
result: list[SubscriptionException] = []
466487
for entry in excluded:
@@ -739,30 +760,21 @@ class _Regime:
739760
#: Whether this regime took over from one that resolved offerings: a
740761
#: cutover, after which a billing offering owes a stub (adcp#8617).
741762
cutover: bool = False
742-
#: Which packages resolve each offering, from each instant on: package
743-
#: exceptions can change the set inside one regime without changing what
744-
#: it resolves (3.3.0-beta.4: a period is owed through the packages
745-
#: resolving its offering that are owed it).
746-
#: Each entry is ``(since, resolving, listed)``: ``listed`` also counts the
747-
#: packages a ``package_ids`` exception takes out, for explanations.
748-
packages: list[tuple[datetime, _PackageMap, _PackageMap]] = field(default_factory=list)
749-
750-
def resolving_packages(
751-
self, offering_id: str, at: datetime, *, excepted: bool = False
752-
) -> frozenset[str]:
753-
"""The packages resolving ``offering_id`` in effect at ``at``.
754-
755-
With ``excepted``, also those an open ``package_ids`` exception removes.
756-
"""
757-
current = self.packages[0] if self.packages else None
758-
for entry in self.packages:
759-
if entry[0] > at:
763+
#: Which packages resolve each offering, from each instant on (3.3.0-beta.4:
764+
#: a period is owed through the packages resolving its offering that are
765+
#: owed it). The set can change inside one regime without changing what
766+
#: it resolves, as when a withdrawn package re-resolves to an offering
767+
#: another package already resolves.
768+
packages: list[tuple[datetime, _PackageMap]] = field(default_factory=list)
769+
770+
def resolving_packages(self, offering_id: str, at: datetime) -> frozenset[str]:
771+
"""The packages resolving ``offering_id`` in effect at ``at``."""
772+
current: _PackageMap = self.packages[0][1] if self.packages else {}
773+
for since, by_offering in self.packages:
774+
if since > at:
760775
break
761-
current = entry
762-
if current is None:
763-
return frozenset()
764-
by_offering = current[2] if excepted else current[1]
765-
return by_offering.get(offering_id, frozenset())
776+
current = by_offering
777+
return current.get(offering_id, frozenset())
766778

767779
def owing_packages(
768780
self,
@@ -1011,7 +1023,9 @@ class _CoverageContext:
10111023
changes: list[AccountTimezoneChange]
10121024
removals: tuple[SubscriptionException, ...]
10131025
package_removals: tuple[SubscriptionException, ...]
1014-
membership_intervals: bool
1026+
#: subscription_version -> whether an ``excluded_by_buyer`` entry overlaps
1027+
#: its span, so membership edits apply in place for it (adcp#8681).
1028+
membership_edited: dict[int, bool]
10151029
ordered: list[datetime]
10161030
selectors: dict[int, SubscriptionSelector]
10171031
in_scope: dict[int, bool]
@@ -1034,7 +1048,6 @@ def regimes(self, buy: SubscriptionBuy) -> list[_Regime | None]:
10341048
self.changes,
10351049
account_id=self.account_id,
10361050
account_operator=self.account_operator,
1037-
package_removals=self.package_removals,
10381051
)
10391052

10401053

@@ -1086,7 +1099,17 @@ def _coverage_context(
10861099
every_removal = subscription_exceptions(excluded, gap_entries)
10871100
removals = tuple(item for item in every_removal if not item.package_ids)
10881101
package_removals = tuple(item for item in every_removal if item.package_ids)
1089-
membership_intervals = any(item.reason == "excluded_by_buyer" for item in every_removal)
1102+
# adcp#8681: only a version whose span an excluded_by_buyer entry overlaps
1103+
# is under in-place membership; another version keeps its own lists.
1104+
buyer_exclusions = [item for item in every_removal if item.reason == "excluded_by_buyer"]
1105+
membership_edited = {
1106+
window.subscription_version: any(
1107+
(window.ends_at is None or item.from_ < window.ends_at)
1108+
and (item.until is None or item.until > window.accepted_at)
1109+
for item in buyer_exclusions
1110+
)
1111+
for window in windows
1112+
}
10901113
ids = [item.offering_id for item in offerings]
10911114
if len(set(ids)) != len(ids):
10921115
raise CoverageInputError("invalid_input", "offering_id values must be unique")
@@ -1109,10 +1132,9 @@ def _coverage_context(
11091132
if item.withdrawn_at is not None:
11101133
points.add(item.withdrawn_at)
11111134
points.update(change.changed_at for change in changes)
1112-
for removal in package_removals:
1113-
points.add(removal.from_)
1114-
if removal.until is not None:
1115-
points.add(removal.until)
1135+
# Package-level exceptions are not resolution changes: they remove periods
1136+
# only when they name every package owed them, so they never start a
1137+
# regime or hand periods over (the reference model, 3.3.0-beta.4).
11161138
ordered = sorted(points)
11171139
selectors = {
11181140
window.subscription_version: SubscriptionSelector.from_subscription(window.configuration)
@@ -1123,7 +1145,7 @@ def _coverage_context(
11231145
window.configuration,
11241146
account_id=account_id,
11251147
account_operator=account_operator,
1126-
membership_intervals=membership_intervals,
1148+
membership_intervals=membership_edited[window.subscription_version],
11271149
)
11281150
for window in windows
11291151
}
@@ -1135,7 +1157,7 @@ def _coverage_context(
11351157
changes=changes,
11361158
removals=removals,
11371159
package_removals=package_removals,
1138-
membership_intervals=membership_intervals,
1160+
membership_edited=membership_edited,
11391161
ordered=ordered,
11401162
selectors=selectors,
11411163
in_scope=in_scope,
@@ -1231,6 +1253,7 @@ def owed_subscription_periods(
12311253
subscription_id = context.subscription_id
12321254
chains = context.chains
12331255
removals = context.removals
1256+
package_removals = context.package_removals
12341257

12351258
owed: dict[tuple[int, str, str, datetime], _Owed] = {}
12361259
for buy in buys:
@@ -1281,7 +1304,13 @@ def owed_subscription_periods(
12811304
# confirmation, per package (3.3.0-beta.4): the period ends
12821305
# after the confirmed_at, or the later added_at, of a
12831306
# package resolving the offering.
1284-
if not regime.owing_packages(resolved.offering.offering_id, start, end, joined):
1307+
owing = regime.owing_packages(resolved.offering.offering_id, start, end, joined)
1308+
if not owing or any(
1309+
item.removes_packages(
1310+
start, buy.media_buy_id, resolved.offering.offering_id, owing
1311+
)
1312+
for item in package_removals
1313+
):
12851314
continue
12861315
flight_start, flight_stop = buy.flight_at(end)
12871316
# An empty flight (stopped at or before it started)
@@ -1367,7 +1396,6 @@ def _regimes(
13671396
*,
13681397
account_id: str = "",
13691398
account_operator: str | None = None,
1370-
package_removals: Sequence[SubscriptionException] = (),
13711399
) -> list[_Regime | None]:
13721400
"""Maximal stretches with one active, in-scope version and one resolution."""
13731401
regimes: list[_Regime | None] = []
@@ -1395,14 +1423,11 @@ def _regimes(
13951423
# does and keeps that result; a buy owes the union of its packages'.
13961424
# 3.3.0-beta.4: at the later of the version's accepted_at and the
13971425
# package's own confirmed_at (the buy's, or its later added_at).
1426+
# A package_ids exception never changes resolution; the owed rule
1427+
# applies it to each period (SubscriptionException.removes_packages).
13981428
found: dict[str, SubscriptionOffering] = {}
13991429
by_offering: dict[str, set[str]] = {}
1400-
listed: dict[str, set[str]] = {}
14011430
for package_id, offering_ids in buy.product_offering_ids():
1402-
removed = any(
1403-
item.removes_package(start, buy.media_buy_id, package_id)
1404-
for item in package_removals
1405-
)
14061431
joined = buy.package_confirmed_at(package_id)
14071432
first_resolved = (
14081433
window.accepted_at if joined is None else max(window.accepted_at, joined)
@@ -1415,14 +1440,9 @@ def _regimes(
14151440
resolves_at=first_resolved,
14161441
at=start,
14171442
):
1418-
listed.setdefault(item.offering_id, set()).add(package_id)
1419-
if not removed:
1420-
found[item.offering_id] = item
1421-
by_offering.setdefault(item.offering_id, set()).add(package_id)
1422-
packages = (
1423-
{key: frozenset(value) for key, value in by_offering.items()},
1424-
{key: frozenset(value) for key, value in listed.items()},
1425-
)
1443+
found[item.offering_id] = item
1444+
by_offering.setdefault(item.offering_id, set()).add(package_id)
1445+
packages = {key: frozenset(value) for key, value in by_offering.items()}
14261446
resolved = tuple(
14271447
_Resolved(
14281448
item,
@@ -1442,11 +1462,11 @@ def _regimes(
14421462
and [item.key for item in previous.resolved] == [item.key for item in resolved]
14431463
):
14441464
previous.until = until
1445-
if previous.packages[-1][1:] != packages:
1446-
previous.packages.append((start, *packages))
1465+
if previous.packages[-1][1] != packages:
1466+
previous.packages.append((start, packages))
14471467
continue
14481468
regime = _Regime(
1449-
start, until, window.subscription_version, resolved, packages=[(start, *packages)]
1469+
start, until, window.subscription_version, resolved, packages=[(start, packages)]
14501470
)
14511471
predecessor = regimes[-1] if regimes else None
14521472
before_deactivation = (

0 commit comments

Comments
 (0)