Skip to content

feat(reporting): write per-offering exclusions across calendars - #3551

Merged
bokelley merged 154 commits into
mainfrom
bokelley/reporting-subscription-dx-exclusions
Oct 31, 2026
Merged

bokelley merged 154 commits into
mainfrom
bokelley/reporting-subscription-dx-exclusions

Conversation

@bokelley

Copy link
Copy Markdown
Contributor

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 targets main because CI runs only for PRs into main.

#3545 made the coverage function honour excluded[].offering_id. This slice makes the seller engine write it.

What changes

  • Per-offering entries. When a condition covers offerings with different period boundaries, the engine writes one excluded[] entry per offering: offering_id plus that offering's cutover instants. Before, it wrote one account-wide entry cut at the latest end across calendars. This follows core/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 vector max-accounts-capacity-per-offering. One calendar, or several with the same schedule, still gets a single entry.
  • Which conditions: capacity, excluded_by_buyer, action_required and overridden, across the subscription's calendars. Also a buy's offering_unsupported after a resolution change, across the calendars of the offerings it lost.
  • Closing. A per-offering entry closes at its own offering's cutover, or at the configuration's active_until for an override.
  • Release gate. perOfferingExclusions is read from the served bundle: excluded[].offering_id in reporting-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.
  • Test. Capacity under match: all across 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 and packages/reporting-storage (PostgreSQL suites run in CI).

Refs #3504

🤖 Generated with Claude Code

bokelley and others added 30 commits October 29, 2026 09:30
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
…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>
bokelley and others added 22 commits October 30, 2026 20:20
…ley/reporting-subscription-dx-advanced

# Conflicts:
#	scripts/check-package-size.mjs
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>
…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>
…eporting-subscription-ledger-service

# Conflicts:
#	src/lib/reporting/subscriptions/engine.ts
…elley/reporting-subscription-dx-errors

# Conflicts:
#	src/lib/reporting/subscriptions/engine.ts
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>
aao-secretariat[bot]
aao-secretariat Bot previously approved these changes Oct 30, 2026

@aao-secretariat aao-secretariat Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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; from takes 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant