feat(compliance): reporting_subscription_probe controller scenario for grants, timezone, and clock

.changeset/reporting-subscription-controller-probe.md

@@ -0,0 +1,5 @@
+---
+"adcontextprotocol": minor
+---
+
+Compliance (experimental): `comply_test_controller` adds the `reporting_subscription_probe` scenario for `media_buy.reporting_subscriptions`. Its operations are `revoke_grant`, `regrant`, `reduce_grant` (new `allowed_tasks` param), `set_account_timezone` (new `timezone` param), and `advance_time` (`target_time`). They act only on the caller's own grant on sandbox accounts and on one virtual clock, `simulated_now`. With them, storyboards can test coverage, `accounts_unauthorized`, gaps, withheld periods, wind-down grants, and timezone cutovers against a remote seller without waiting on wall-clock boundaries.

docs/building/by-layer/L3/comply-test-controller.mdx

@@ -625,6 +625,34 @@ Reset with `prepare` before the negative fixture, then call:
 }
 ```
 
+### `reporting_subscription_probe`
+
+Experimental (`media_buy.reporting_subscriptions`). It drives the inputs that
+[reporting-subscription coverage](/docs/media-buy/task-reference/get_reporting_status#subscription-coverage)
+depends on but a buyer can't change itself: the caller's grant on an account, the
+account's timezone, and the clock. A storyboard can then check, against a remote
+seller, that coverage, `accounts_unauthorized[]`, `gaps[]`, `timezone_cutovers[]`,
+and withheld periods follow the spec. Seed buys with `seed_media_buy`.
+
+The probe acts only on sandbox accounts and only on the authenticated caller's own
+grant. It runs on one virtual clock, `simulated_now`, which every authorization
+timestamp, cutover, period boundary, obligation, and delivery for the caller's
+sandbox accounts uses. A revoked account is unknown to every other task, as the spec
+requires, but the controller still accepts `regrant` and `advance_time` for it.
+
+| Operation | Params | Required observable result |
+|---|---|---|
+| **revoke_grant** | `account_id` | End the caller's authority for the account at `simulated_now`. The account reads as unknown to [`get_reporting_status`](/docs/media-buy/task-reference/get_reporting_status) and every other task. Each covering subscription lists it in `accounts_unauthorized[]` on [`get_principal`](/docs/protocol/get_principal), with `unauthorized_at` equal to `simulated_now`. Return `unauthorized_at`. |
+| **regrant** | `account_id` | Restore the grant at `simulated_now`. Before `unauthorized_at` plus `status_retention_days`, this continues the chain: `authorization.authorized_at` is unchanged, the account leaves `accounts_unauthorized[]`, and withheld periods are owed again. Later, it starts a new chain with `authorized_at` equal to `simulated_now`. Return `authorized_at`, `chain` (`continued` or `new`), and `regranted_at` when the chain continued. |
+| **reduce_grant** | `account_id`, `allowed_tasks` | Replace the caller's `allowed_tasks` on the account, with `read_only: false`, at `simulated_now`. A list that keeps `get_reporting_status` keeps the account covered (the wind-down grant). A list without it takes the account out of coverage. Tasks the list drops fail for the account with [`SCOPE_INSUFFICIENT`](/docs/building/verification/compliance-catalog#error-code-scope-insufficient). Return the applied `allowed_tasks`. |
+| **set_account_timezone** | `account_id`, `timezone` | Change the account's timezone at `simulated_now`, as an applied account change: [`list_accounts`](/docs/accounts/tasks/list_accounts) shows the new `timezone` and a new `revision`. Account-timezone periods cut over at the first old-timezone boundary at or after the change, recorded in `timezone_cutovers[]`. Return `previous_timezone`, `timezone`, and the `effective_at` cutover instant for each affected offering. |
+| **advance_time** | `target_time` | Move `simulated_now` forward to `target_time`. Reject a time at or before the current `simulated_now`. Every period boundary crossed is processed as in production: obligations are committed, subscriptions resolve, deliveries are attempted, and authority is re-checked. Return the applied `simulated_now`. |
+
+Every successful response is a `SimulationSuccess` whose `simulated` object carries
+`simulated_now` and, except for `advance_time`, `account_id`. The operations are
+convergent: repeating one at the same `simulated_now` returns the same result, and
+none mutates state outside the caller's sandbox accounts.
+
 ### `force_create_media_buy_arm`
 
 Shapes the next [`create_media_buy`](/docs/media-buy/task-reference/create_media_buy) call from the caller's authenticated sandbox account into a specific response arm. v1 supports two arms: `submitted` (the async task envelope, no `media_buy_id` yet) and `input-required` (the errors-branch). Unlike `force_media_buy_status`, no entity transitions — there is no media buy yet — so the response carries `forced.arm` rather than `previous_state`/`current_state`.

package.json

@@ -33,7 +33,7 @@
     "verify:schema-discovery": "node scripts/verify-schema-discovery.mjs",
     "typecheck": "tsc --project server/tsconfig.json --noEmit && npm run typecheck:fixed-trace-rollout-tests",
     "typecheck:fixed-trace-rollout-tests": "node scripts/typecheck-fixed-trace-rollout-tests.mjs",
-    "test:schemas": "node tests/schema-validation.test.cjs && node --test tests/seller-offers-contract.test.cjs tests/service-commitments.test.cjs tests/sync-platform-id.test.cjs tests/assignment-landing-page.test.cjs tests/assignment-trackers.test.cjs tests/outcome-target.test.cjs tests/trusted-match-offer-creative-data.test.cjs tests/accessibility-violation-details.test.cjs tests/portfolio-routing-scope.test.cjs tests/catalog-item-availability-updates.test.cjs tests/catalog-ingestion-capabilities.test.cjs tests/sdk-implementation-metadata.test.cjs tests/seller-optimized-package-controls.test.cjs tests/compact-product-lifecycle-storyboards.test.cjs tests/timezone-resolution-storyboards.test.cjs tests/terminal-package-retention-storyboard.test.cjs tests/total-budget-redistribution-currency.test.cjs tests/dooh-allocation.test.cjs tests/x-added-in-3-3-sweep.test.cjs tests/performance-standard-metric-id.test.cjs tests/identity-absence-coherence.test.cjs tests/execution-requirements.test.cjs tests/execution-readiness.test.cjs tests/schema-deprecation-metadata.test.cjs tests/products-only-brief-compatibility.test.cjs tests/price-adjustments-vectors.test.cjs tests/async-identity-convergence.test.cjs tests/creative-rotation.test.cjs tests/creative-start-policy.test.cjs tests/canonical-forecast-point-parity.test.cjs tests/creative-revisions.test.cjs tests/creative-live-updates.test.cjs tests/creative-delivery-contracts.test.cjs tests/tracker-execution-contracts.test.cjs tests/tracker-execution-package-integration.test.cjs tests/metric-identity-coherence.test.cjs tests/print-metrics.test.cjs tests/installment-lifecycle-reporting.test.cjs tests/rights-channel-restrictions.test.cjs tests/daypart-time-of-day.test.cjs tests/audience-size-range.test.cjs tests/media-buy-lineage.test.cjs tests/delivery-projection.test.cjs tests/viewable-rate-optimization-goal.test.cjs tests/sort-contract-delivery-reporting.test.cjs tests/time-based-views-contract.test.cjs tests/metric-qualifier-parity.test.cjs tests/collection-mechanism.test.cjs tests/requested-metrics-contract.test.cjs tests/auto-breakdown-negotiation-contract.test.cjs tests/format-delivery-reporting-contract.test.cjs tests/inventory-delivery-reporting-contract.test.cjs tests/property-delivery-conformance.test.cjs tests/lint-schema-enum-drift.test.cjs tests/lint-schema-required-declared.test.cjs tests/format-asset-type-parity.test.cjs tests/canonical-manifest-constructibility.test.cjs tests/synthetic-depiction.test.cjs tests/creative-rendering-authority.test.cjs tests/buyer-reason.test.cjs tests/mutation-outcome.test.cjs tests/error-recovery-vectors.test.cjs tests/reporting-status-contract.test.cjs tests/reporting-reconciliation-fixture.test.cjs tests/reporting-core-fixture.test.cjs tests/reporting-native-version-ref-bounds.test.cjs tests/trust-json-v1.test.cjs tests/refine-proposals-expected-confirmation-at.test.cjs tests/structured-package-refine.test.cjs tests/hold-policy.test.cjs tests/hold-policy-vectors.test.cjs tests/canonical-installments.test.cjs tests/withdrawn-to-4-0.test.cjs tests/collection-catalog.test.cjs tests/collection-copies-vectors.test.cjs tests/account-change-record.test.cjs tests/notification-config-payload-view.test.cjs tests/account-requests.test.cjs tests/reporting-subscriptions.test.cjs tests/reporting-subscription-coverage-vectors.test.cjs tests/reporting-subscription-coverage-properties.test.cjs tests/product-roster-coverage-vectors.test.cjs && npm run test:premium-display-formats && npm run test:geo-region-targeting",
+    "test:schemas": "node tests/schema-validation.test.cjs && node --test tests/seller-offers-contract.test.cjs tests/service-commitments.test.cjs tests/sync-platform-id.test.cjs tests/assignment-landing-page.test.cjs tests/assignment-trackers.test.cjs tests/outcome-target.test.cjs tests/trusted-match-offer-creative-data.test.cjs tests/accessibility-violation-details.test.cjs tests/portfolio-routing-scope.test.cjs tests/catalog-item-availability-updates.test.cjs tests/catalog-ingestion-capabilities.test.cjs tests/sdk-implementation-metadata.test.cjs tests/seller-optimized-package-controls.test.cjs tests/compact-product-lifecycle-storyboards.test.cjs tests/timezone-resolution-storyboards.test.cjs tests/terminal-package-retention-storyboard.test.cjs tests/total-budget-redistribution-currency.test.cjs tests/dooh-allocation.test.cjs tests/x-added-in-3-3-sweep.test.cjs tests/performance-standard-metric-id.test.cjs tests/identity-absence-coherence.test.cjs tests/execution-requirements.test.cjs tests/execution-readiness.test.cjs tests/schema-deprecation-metadata.test.cjs tests/products-only-brief-compatibility.test.cjs tests/price-adjustments-vectors.test.cjs tests/async-identity-convergence.test.cjs tests/creative-rotation.test.cjs tests/creative-start-policy.test.cjs tests/canonical-forecast-point-parity.test.cjs tests/creative-revisions.test.cjs tests/creative-live-updates.test.cjs tests/creative-delivery-contracts.test.cjs tests/tracker-execution-contracts.test.cjs tests/tracker-execution-package-integration.test.cjs tests/metric-identity-coherence.test.cjs tests/print-metrics.test.cjs tests/installment-lifecycle-reporting.test.cjs tests/rights-channel-restrictions.test.cjs tests/daypart-time-of-day.test.cjs tests/audience-size-range.test.cjs tests/media-buy-lineage.test.cjs tests/delivery-projection.test.cjs tests/viewable-rate-optimization-goal.test.cjs tests/sort-contract-delivery-reporting.test.cjs tests/time-based-views-contract.test.cjs tests/metric-qualifier-parity.test.cjs tests/collection-mechanism.test.cjs tests/requested-metrics-contract.test.cjs tests/auto-breakdown-negotiation-contract.test.cjs tests/format-delivery-reporting-contract.test.cjs tests/inventory-delivery-reporting-contract.test.cjs tests/property-delivery-conformance.test.cjs tests/lint-schema-enum-drift.test.cjs tests/lint-schema-required-declared.test.cjs tests/format-asset-type-parity.test.cjs tests/canonical-manifest-constructibility.test.cjs tests/synthetic-depiction.test.cjs tests/creative-rendering-authority.test.cjs tests/buyer-reason.test.cjs tests/mutation-outcome.test.cjs tests/error-recovery-vectors.test.cjs tests/reporting-status-contract.test.cjs tests/reporting-reconciliation-fixture.test.cjs tests/reporting-core-fixture.test.cjs tests/reporting-native-version-ref-bounds.test.cjs tests/trust-json-v1.test.cjs tests/refine-proposals-expected-confirmation-at.test.cjs tests/structured-package-refine.test.cjs tests/hold-policy.test.cjs tests/hold-policy-vectors.test.cjs tests/canonical-installments.test.cjs tests/withdrawn-to-4-0.test.cjs tests/collection-catalog.test.cjs tests/collection-copies-vectors.test.cjs tests/account-change-record.test.cjs tests/notification-config-payload-view.test.cjs tests/account-requests.test.cjs tests/reporting-subscriptions.test.cjs tests/reporting-subscription-probe.test.cjs tests/reporting-subscription-coverage-vectors.test.cjs tests/reporting-subscription-coverage-properties.test.cjs tests/product-roster-coverage-vectors.test.cjs && npm run test:premium-display-formats && npm run test:geo-region-targeting",
     "test:performance-feedback": "node --test --test-force-exit --test-timeout=30000 tests/performance-feedback-contract.test.cjs",
     "test:dist-schema-version-ids": "node --test --test-force-exit --test-timeout=30000 tests/dist-schema-version-ids.test.cjs",
     "test:examples": "node tests/example-validation-simple.test.cjs && npm run test:tmp-context-merge",