Skip to content

fix(reporting): run the canonical coverage vectors and fix the two bugs they expose - #3545

Merged
bokelley merged 144 commits into
mainfrom
bokelley/reporting-subscription-dx-vectors
Oct 31, 2026
Merged

bokelley merged 144 commits into
mainfrom
bokelley/reporting-subscription-dx-vectors

Conversation

@bokelley

@bokelley bokelley commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

Vectors slice for #3504, added at the coordinator's request: the canonical spec coverage vectors and the two bugs they expose. It stacks on #3544 (T3) → #3543 → #3542 → #3534 and the rest of the #3504 stack. Review only test(reporting): run the canonical reporting-subscription coverage vectors. It targets main because CI runs only for PRs into main. T4 (naming) stacks on top.

Upstream pin

File sha256
vectors.json (113 cases) b392df771fc2bf635c5c441ff2dd5107e1cda13ab483fe902a6a56661f5e7904
case.schema.json 0550b51097ea2c9a6bbd8721de5b5855acfcbd097dff31edeb0df2f397f7dc42
error-codes.json 4e8e5142ada936fc8923735155d786a0801258922fb85b492785730479713481
reason-codes.json 2574b2a32fb8260fc7f9a7d9cd1eac1b588aa22c54a350e54964a893b80e77c4
  • The parity test fails when a hash differs from the pin. npm run sync:reporting-subscription-vectors -- --commit <sha> [--from <spec checkout>] refreshes the mirror from GitHub raw or a local checkout, and rewrites the pin.
  • The Python SDK runs the same vectors.

What changes

  • Parity test. test/lib/reporting-subscription-coverage.test.js runs every case strictly: rows and grouped obligations, or expected_error code and detail. It also validates every case against case.schema.json. test/fixtures/reporting-subscriptions/coverage-cases.json is deleted.
  • tzdata. The vectors are pinned to 2026f and hold from 2026b. On a runtime whose bundled tzdata predates 2026b, a failing case that depends on a non-UTC zone is reported as t.skip with a reason naming the runtime's release. UTC-only and expected_error cases always run strictly. Locally, Node 24 with tzdata 2026b ran all 113 cases with no skips. CI's unit lane uses Node 20.x, so any skips there show in the test output.
  • Bug fix: excluded[].offering_id is honoured. An entry with offering_id removes only that offering's periods. It used to be applied to every offering, which dropped a period in max-accounts-capacity-per-offering. The coverage input type gains ReportingSubscriptionExclusionEntryV1 (offering_id?), and the engine's ReportingSubscriptionExclusionV1 carries the field.
  • Bug fix: P1W is refused. A selector period_duration outside the schedule pattern now throws CoverageInputError COVERAGE_INPUT_INVALID / invalid_period_duration. It used to resolve no offering and silently owe nothing.
  • Corrected cases. The five managed offerings that were schema-invalid in the ported cases (missing method.provider/method.format, receipt offerings without canonicalization_*) existed only in the retired coverage-cases.json. The other in-repo managed-offering fixtures already carry provider and format.
  • numeric offset timezone is refused now uses an account_timezone offering and passes unchanged (invalid_timezone).
  • Error test. test/lib/reporting-subscription-errors.test.js now reads the vendored error-codes.json. Each of its 14 codes is checked against the TS class it names, its recovery and its dispatched rule.
  • Package budget. The packed-byte bump now lives in feat(reporting): typed reporting-subscription errors with code, recovery and dispatched #3544 (26,560,000). Measured at this slice with main (beta.2): 26,526,144 bytes.

Deviations and follow-ups

  • Engine exclusions. The engine still writes account-wide exclusions, cut at the latest end across calendars, rather than one entry per offering. The coverage function and the engine's own coverage now honour offering_id wherever it appears. Writing per-offering entries is seller-side work for a later slice.
  • Reason codes. reason-codes.json is vendored but nothing in TS emits trace reasons yet (T12). No conflicting names were introduced.

Checks

npm run typecheck, lint:boundaries, check:package-size, Prettier, and the reporting-subscription, principal and reliable-reporting suites (381 tests).

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>
…ley/reporting-subscription-dx-advanced

# Conflicts:
#	scripts/check-package-size.mjs

@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 — no changes to review.

The head tree (df6845d) is byte-for-byte identical to the previously approved SHA (e7a74e9); git diff between them resolves to 0 files, with the intervening commits being stack merges that left the tree unchanged. No critical/high/medium findings in this pass, and the prior pass recorded no blockers.

Decision table: rows 1–8 do not fire (no findings, gated_paths false, high_risk false, no team gate, prior decision was approve). Falls through to row 9 → approve.

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 — subsequent pass, clean.

The delta since the prior approved pass is a single hunk in scripts/check-package-size.mjs adding three explanatory comment lines documenting the AdCP 3.3 reporting-subscription coverage budget rationale (~26.37M packed bytes, ~40 KB variance allowance). No code behavior change, no cap-constant change in the delta — MAX_PACKED_TARBALL_BYTES and the #3544 cap bump sit above this hunk and were already present in prior approved passes. Documentation prose in a build script; nothing clears the Medium bar.

No blocking findings, no medium findings. No high-risk flag, no gated paths, no author-team gate. Rows 1–8 do not fire; outcome falls through to row 9 (approve).

bokelley and others added 14 commits October 30, 2026 22:24
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
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 — subsequent pass on a clean delta with no blocking findings.

This is a follow-up pass; the prior decision was also a clean approve. The delta is 3 source + 3 test files refining the reporting-subscription engine:

  • calendar.ts:9-18 — fail-closed refusal of sub-daily billing_cycle alignment (adcp#8622) instead of silent local-midnight alignment. Correct shape.
  • engine.ts:798-810 — refreshes an open action_required entry's pending_action on change (canonicalize-compared, preserves from); latestPeriodEnd (engine.ts:42-46) replaces withheld.at(-1) safely since periods are appended out of end order and periods[0]! is guarded by the caller.
  • reporting-subscriptions.ts:89 (!== true → === false) correctly preserves a pending replace retry across flag-omitting writes.

Each change has a dedicated test in the same delta and changesets are present. No Critical/High/Medium findings.

Decision table: no critical/high findings (row 1 N/A); gated_paths false (row 2 N/A); high_risk false (rows 3/5 N/A); no medium findings (rows 4/8 N/A); no no-auto-approve team match (row 7 N/A); prior decision was approve so sticky escalation (row 6) does not apply. Falls through to row 9 → approve. review_decision REVIEW_REQUIRED does not block approval since gated_paths is false.

@bokelley
bokelley merged commit 935363c into main Oct 31, 2026
45 checks passed
@bokelley
bokelley dismissed aao-secretariat[bot]’s stale review October 31, 2026 14:19

The merge-base changed after approval.

@bokelley
bokelley deleted the bokelley/reporting-subscription-dx-vectors branch October 31, 2026 14:19
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