Repository navigation
feat(reporting): write per-offering exclusions across calendars - #3551
Merged
Merged
Conversation
Add the pure expectedSubscriptionPeriods rule for AdCP 3.3 principal-level reporting subscriptions (experimental media_buy.reporting_subscriptions), the normative period_generation calendar it uses, selector resolution (exact, finest, all with byte-order ties), scope membership, and a builder for the 3.3 registration capabilities (configuration_tasks, the deprecated configuration_task, and the subscriptions block). createAdcpServerFromPlatform adds media_buy.reporting_subscriptions to experimental_features only beside a subscriptions block. installConfiguration now throws a typed ReportingConfigurationImmutableError with the unchanged message. The cross-SDK parity table is test/fixtures/reporting-subscriptions/coverage-cases.json. Refs #3504 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…al ships Advertising media_buy.reporting_subscriptions also requires adcp.principal.supported_sections to list reporting_subscriptions, which the SDK does not emit yet. Keep the capability builder pure in this slice and add the feature id together with the principal block in the runtime slice, so an adopter can never produce a 3.3-invalid capabilities response. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Adopt the rules adcontextprotocol/adcp#8585 settled: - Selection reads each offering's published standard_dimensions and unmapped_dimensions, and fails closed on an offering without them. - period_timezone: a utc offering matches only UTC or Etc/UTC; a source_timezone offering only its own published zone (never an account-resolved one). - The coverage function takes the readback's inactive_intervals in wire shape, per-offering timezone_cutovers with previous_timezone (account.timezone is now the current zone), and per-offering gaps. - The parity table fixes the billing-cycle case's scope (both keys, which maxProperties 1 forbids), adds cases for the settled rules, and its subscriptions are now schema-validated. The new wire fields are hand-modeled in subscriptions/wire.ts until 3.3.0-beta.2 ships. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
- An empty flight (stop at or before start) overlaps nothing. - A cutover carries the outgoing stretch's own owing start into E, so two cutovers inside one period never owe a period twice. - Sub-daily periods under a local alignment restart at each local midnight on wall-clock multiples (adcp#8588); calendars gain next() and the walk iterates by instant with an iteration budget and skip-ahead. - A billing anchor in a DST fold is interval zero itself. - A wire authorized_at equal to the chain start continues the chain. - The start rule lives in one function for the pending owner decision. - Schema validation accepts unknown reporting-dimension values. - The parity table grows to 79 cases with obligations on every case and non-wire inputs labelled. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The start bound is the first boundary at or after the later of the version's accepted_at and the account's authorized_at; a buy is owed every period that ends after its confirmed_at and overlaps its flight, so the period in which the buy is confirmed is owed in full. The rule stays in firstOwedBoundary. Parity table: the mid-period confirmed_at and hourly cases change, plus every case whose first period contains confirmed_at; new cases for an ASAP buy confirmed mid-day and a monthly billing buy confirmed on the 12th. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…time
Opt-in support for the AdCP 3.3 sync_principal reporting_subscriptions
section (experimental media_buy.reporting_subscriptions):
- createPrincipalLifecycle({ reportingSubscriptions }) validates, versions
and reads back subscriptions (core/reporting-subscription-state.json),
honours dry_run and expected_configuration_version, applies
replace_account_configs once per version through a host hook, derives
action_required from the destination, and emits principal.changed with
reason reporting_subscription_changed. It also exposes the adcp.principal
capability block.
- createReportingSubscriptionEngineV1 turns three host hooks into grant
history, max_accounts slots, precedence, exceptions at cutover instants,
timezone cutovers, re-grant gaps, accounts_unauthorized, the receipt
roster and the post-loss receipt window, and computes owed periods with
the same expectedSubscriptionPeriods rule buyers run.
- createReliableReportingService({ reportingSubscriptions }) advertises
configuration_tasks and the subscriptions block and adds
subscription_coverage to summary and periods views.
- createAdcpServerFromPlatform passes capabilities.principal and
capability_changes through, adds protocol.principal and
media_buy.reporting_subscriptions to experimental_features, refuses
subscriptions without the reporting_subscriptions section, and strips
3.3-only fields for callers pinned below 3.3.
Without the options every response is byte-for-byte unchanged; a golden
transcript captured from the pre-change runtime proves it.
Refs #3504
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
… by release - readFacts refuses a roster that does not finish within the page cap, as it already did for a repeating cursor: a partial roster would read as revocations and fabricate accounts_unauthorized entries. - Callers pinned below 3.2 no longer see protocol.principal once the adcp.principal block is removed for them. - subscription_coverage is added only for callers served 3.3 or later; earlier get_reporting_status response shapes are closed. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The placeholder regex backtracked polynomially on runs of '{' (CodeQL).
Tokenize braces in a single pass instead, which also rejects nested and
unbalanced braces explicitly.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
… test Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
- The principal readback lists inactive_intervals; the engine feeds them to the coverage function in wire shape. - Timezone cutovers carry previous_timezone and gaps are recorded per offering_id when covered offerings' boundaries differ. - authorized_at is the start of the authorization chain: a re-grant inside retention keeps it, so the engine stamps the re-grant when authority is observed again. - The service requires standard_dimensions on every offering when subscriptions are advertised. - Responses served at 3.3.0-beta.1 omit the fields its closed schemas do not define; they reach callers served 3.3.0-beta.2 or later. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…ts, sharded engine state Addresses the expert review of the subscription runtime: - Owed periods are frozen as they elapse and never recomputed; pruning past status_retention_days never re-owes or drops an elapsed period. A product, package or offering change applies from the E of its observation, and periods of that buy starting earlier keep resolving from the buy as it was. - Change instants come from source data (granted_at, timezone_changed_at, resolveRevocationInstant, the overriding configuration's active_until). - The engine store is sharded per principal and per account; the receipt roster is tenant-scoped; an unobserved revocation followed by a new chain opens a gap. - replace_account_configs runs after commit and is retried on failure; a destination transport change needs a version; inactive_intervals over 64 is rejected; shared path_templates that can expand to the same path are rejected; the delivery-config clash check is required unless opted out; coverage recording rejects oversized lists and no longer bumps configuration_version. - Post-beta.1 fields are gated on the served bundle's schema, and an unknown served version emits none of them. prior_versions[] carries configuration (adcp#8588). Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…counts A small max_accounts against a large roster gives every account past the cap a capacity exception, which can exceed the readback's 1000-entry limit. The reconcile used to throw for the whole principal on every pass. Now that subscription keeps its last published lists, every other subscription still updates, and the pass reports it in readback_overflow and through onReadbackOverflow. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…criptions - syncReportingSubscriptionsV1 writes and reads back the reporting_subscriptions section through the guarded sync_principal lifecycle. - reportingSubscriptionVersionRecordsV1 rebuilds coverage version records from the readback plus the buyer's own per-version configurations, and subscriptionExpectedReportingPeriodsV1 maps owed obligations onto the consumer runtime's ExpectedReportingPeriod. - The consumer runtime takes a per-account subscriptionExpectations hook fed with the summary view's subscription_coverage, and refreshes on an authenticated principal.changed through handleAuthenticatedPrincipalChanged. - createReportingSubscriptionEngineStateStoreV1 persists engine state as one CAS document per principal on any AdcpStateStore; PostgresStateStore makes it durable with no further migration. A PostgreSQL restart test joins the CI backend-contracts step. Refs #3504 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…ords Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…he buyer side reportingSubscriptionVersionRecordsV1 no longer takes buyer-recorded inactive intervals: the readback's inactive_intervals (adcp#8585) pass to expectedSubscriptionPeriods unchanged. Test offerings publish standard_dimensions. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
listPrincipals feeds the receipt roster, so a list cut short at the page cap, or a repeating cursor, now throws instead of returning a partial list, matching the authorized-account walk. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
- The engine state store follows the engine's sharded interface: one CAS document per principal and per (principal, account), with listKeys and a tenant-scoped listPrincipals. - Subscription expectations get the summary's ledger_as_of (minus an optional grace) as now, and the hook is documented as requiring a seller that materializes subscription obligations. - Expectation templates must supply coverage; the old default could never match an obligation reporting packages or partial coverage. - principal.changed redeliveries are dropped by idempotency_key, and a burst during a run joins one trailing run. - syncReportingSubscriptionsV1 refuses a deactivation by omission unless allowDeactivation, checked against every configuration read it replaces, and verifies the stored configuration field by field. - reportingSubscriptionVersionRecordsV1 falls back to the readback's configuration and prior_versions[].configuration (adcp#8588). Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Owed-set generations for AdCP 3.3 principal-level reporting subscriptions (#3504): one generation per (account, owning principal, subscription_id, subscription_version, resolved offering), with an immutable `subscription` block and a mutable `owedSet` horizon outside the fingerprint. - producer.planSubscriptionObligations installs each generation once, writes every frozen owed obligation with its own period, media buys and constituents (periodOrdinal = start second), and then advances owedSet.through on every generation the subscription owns. - Coverage treats an owed set as complete by construction: gaps are not owed, so there is no continuity error, and the scope stays open until owedSet.through reaches its end. - get_reporting_status, get_media_buy_delivery and sync_reporting_status scope subscription generations to the caller's principal (resolveSubscriptionPrincipal, snapshot `subscription_principal`). - Status ingest accepts a status without reporting_obligation_id against an owed set only for an existing owed obligation. - PostgreSQL: additive `subscription_key` column and a unique index on (account_id, delivery_config_id, delivery_config_version, subscription_key) replacing the three-column constraint, found and dropped by its columns. Mirrored in the memory test store. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…vice
createReliableReportingService({ reportingSubscriptions }) now writes the
engine's frozen owed sets into the ledger every cycle, before account
configurations, and the worker executes them (#3504).
- engine.frozenOwedSets(principal, { accountId? }) returns each
subscription's frozen obligations, horizon and version configurations;
engine.listPrincipals(tenantId) lists principals from the engine store.
- Generations go through the same trusted path as installConfiguration
(resolveSource, resolveCurrency, resolveCoverage), with seller policy from
the new resolveSubscriptionConfiguration hook. Each obligation freezes the
authorized constituents of exactly the media buys it owes.
- New options: listSubscriptionPrincipals (required),
resolveSubscriptionConfiguration (required), resolveSubscriptionAccount and
onPlanningError. Planning failures are isolated per subscription.
- resolvePrincipal now also scopes get_reporting_status,
get_media_buy_delivery and sync_reporting_status to the caller's own
subscription generations.
- Without reportingSubscriptions the service is byte-for-byte unchanged,
proven by a golden transcript captured from the service before the change.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…ntime timezone data A source-calendar P1D generation freezes the runtime's tzdb and ICU versions and the install day into its identity, so the golden differed on CI runners. The transcript now uses a UTC-aligned offering; the golden is recaptured from #3509's head (800adfc) and still matches byte for byte. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Deliver principal-level reporting subscription obligations (#3504) to the owner's destination through managed delivery. - Destination resolution: the Core service calls a new reportingSubscriptions.bindManagedGeneration hook (through the planner's bindGeneration) before a managed generation's first obligation. The production service supplies createReportingSubscriptionManagedBindingV1: version destination_id -> the owner's current destination generation (delivery-eligible, pattern and transport matching the frozen destination_method) -> a per-account authorization of that destination_ref (ensureDestinationAuthorization) -> an immutable binding that freezes path_template. - Bindings are keyed by their Core configuration: the managed migration drops the published (account, delivery_config_id, delivery_config_version) key, found by its columns. - path_template is expanded per obligation and passed to adapters as delivery_path; object-store names place it inside the collision-free generation prefix. Subscription revision rows carry account_id inside the committed digest. - The managed worker re-checks the owner's account authority before delivering and before settling; a lost grant holds the materialization without spending an attempt, so the obligation stays owed. - Status subscribers and notification activity reach only the owner of a subscription obligation. Production reads are scoped to the caller's principal and carry subscription_coverage. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
# Conflicts: # scripts/check-package-size.mjs
…ley/reporting-subscription-ledger-service
…to bokelley/reporting-subscription-delivery
…bscription-coverage # Conflicts: # scripts/check-package-size.mjs
…dules after merging main Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…/reporting-subscription-runtime # Conflicts: # scripts/check-package-size.mjs
…er merging main Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…reporting-subscription-consumer
…/reporting-subscription-conformance
…ley/reporting-subscription-dx-advanced # Conflicts: # scripts/check-package-size.mjs
…ley/reporting-subscription-dx-revocation
…elley/reporting-subscription-dx-errors
…y/reporting-subscription-dx-vectors
…ey/reporting-subscription-dx-naming
A sub-daily billing_cycle was routed to the local sub-daily calendar, which aligns to local midnight and ignores period_anchor, so every boundary was off by the anchor's time of day. adcontextprotocol/adcp#8622 makes a sub-daily billing_cycle invalid; refuse it. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…/reporting-subscription-runtime
…nt_configs A later write that merely omitted replace_account_configs cleared both the applied marker and a committed-but-unconfirmed replacement, so a failed host hook was silently abandoned. An omitted flag now leaves both untouched; an explicit false clears them, so a later true applies again. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…t owed period end - An open action_required exception now takes the host's current pending_action (url, message, reason) when it changes, keeps its from, and notifies principal.changed. It used to keep the first action forever. - accounts_unauthorized last_owed_period_end takes the latest frozen period_end. Frozen periods are not stored in end order, so the last entry could under-state the window. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…reporting-subscription-consumer
…/reporting-subscription-ledger
…eporting-subscription-ledger-service # Conflicts: # src/lib/reporting/subscriptions/engine.ts
…kelley/reporting-subscription-delivery
…/reporting-subscription-receipts
…/reporting-subscription-conformance
…ley/reporting-subscription-dx-advanced
…ley/reporting-subscription-dx-revocation
…elley/reporting-subscription-dx-errors # Conflicts: # src/lib/reporting/subscriptions/engine.ts
…y/reporting-subscription-dx-vectors
…ey/reporting-subscription-dx-naming
When the offerings a condition covers have different period boundaries, the engine now writes one excluded[] entry per offering with offering_id and that offering's cutover instants (capacity, excluded_by_buyer, action_required, overridden, and offering_unsupported after a resolution change). Before, it wrote one account-wide entry cut at the latest end. A per-offering entry closes at its own offering's cutover. A release whose excluded[] has no offering_id gets them folded back into one entry. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Ladon verdict: Approve
Approve — clean review, no blocking or medium findings.
The reviewer examined the designated slice (commit 8997e1d, "write per-offering exclusions across calendars"; 4 files, 140 insertions). Key checks:
- engine.ts: perOfferingExclusions splits excluded[] per offering only when calendar keys differ; calendar resolution uses the correct offering_id-keyed Map; the settleExclusions Iterable→ReadonlyMap signature change has a single consistent caller.
- release.ts: collapsePerOfferingExclusions folds entries back for releases without excluded[].offering_id; grouping by canonicalize(condition) works because stripExclusion removes the per-offering key;
fromtakes the latest cutover (pre-PR behavior); open offerings keep the folded entry open. - Changeset: minor is correct (experimental surface, gated release field), and the DR-0033 fold-back pathway is present with a test.
No critical/high/medium findings. gated_paths is false, high_risk is false, no no-auto-approve team match, and no prior decision. Although review_decision is REVIEW_REQUIRED, row 2 only applies when gated_paths is true — it is false here, so no hard gate fires. None of rows 1–8 match; the outcome falls through to row 9: approve.
This was referenced Oct 30, 2026
Merged
bokelley
dismissed
aao-secretariat[bot]’s stale review
October 31, 2026 14:20
The merge-base changed after approval.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Per-offering exclusions for #3504. It stacks on #3546 (naming) → #3545 → #3544 → #3543 → #3542 → #3534 and the rest of the #3504 stack. Review only
feat(reporting): write per-offering exclusions across calendars. It targetsmainbecause CI runs only for PRs intomain.#3545 made the coverage function honour
excluded[].offering_id. This slice makes the seller engine write it.What changes
excluded[]entry per offering:offering_idplus that offering's cutover instants. Before, it wrote one account-wide entry cut at the latest end across calendars. This followscore/reporting-subscription-coverage.json: "when the account's covered offerings have different period boundaries; from and until are then that offering's cutover instants". It matches the canonical vectormax-accounts-capacity-per-offering. One calendar, or several with the same schedule, still gets a single entry.capacity,excluded_by_buyer,action_requiredandoverridden, across the subscription's calendars. Also a buy'soffering_unsupportedafter a resolution change, across the calendars of the offerings it lost.active_untilfor an override.perOfferingExclusionsis read from the served bundle:excluded[].offering_idinreporting-subscription-coverage.json, which 3.3.0-beta.2 defines. A release without it gets the entries folded back into one entry cut at the latest instant, which is what the engine wrote before.match: allacross a UTC calendar and an account-timezone calendar writes four entries, from 11-02T00 for the UTC offerings and 11-02T05 for the New York one. The buyer's computed owed set agrees. The folded projection is one entry at the latest instant.Checks
npm run typecheck,lint:boundaries,check:package-size, Prettier, and 1,281 tests across reporting, principal, server-decisioning andpackages/reporting-storage(PostgreSQL suites run in CI).Refs #3504
🤖 Generated with Claude Code