feat(reporting): one storage decision with versioned migrations

.changeset/reporting-subscription-consumer.md

@@ -0,0 +1,18 @@
+---
+'@adcp/sdk': minor
+---
+
+Buyer runtime and durable storage for AdCP 3.3 principal-level reporting subscriptions (experimental `media_buy.reporting_subscriptions`, #3504).
+
+- `syncReportingSubscriptionsV1(client, subscriptions, options)` writes the complete `reporting_subscriptions` set through the guarded `sync_principal` lifecycle.
+  - It refuses, before writing, to deactivate an active subscription by omission unless `allowDeactivation: true`. Sending `active: false` is always allowed.
+  - It checks that every submitted subscription reads back at its version and activation state, and that every submitted configuration field is stored unchanged.
+- `reportingSubscriptionVersionRecordsV1({ state, configurations? })` rebuilds the coverage function's version records from the readback (`accepted_at`, `prior_versions`, `deactivated_at`). Each version's configuration comes from the buyer's own records, or else from the readback: the current `configuration`, and `prior_versions[].configuration` from sellers on 3.3.0-beta.2 (adcp#8588). Pass the readback's `inactive_intervals` to `expectedSubscriptionPeriods` unchanged.
+- `subscriptionExpectedReportingPeriodsV1(obligations, template)` turns owed obligations into the consumer runtime's `ExpectedReportingPeriod`s. The template must supply `coverage`; no default could match an obligation that reports packages or partial coverage.
+- The reliable reporting consumer runtime accepts a per-account `subscriptionExpectations` hook. It reads the summary view's `subscription_coverage[]` before each reconciliation and reconciles the returned periods alongside configuration-derived ones.
+  - The hook's `now` is the summary's `ledger_as_of` minus `subscriptionExpectationGraceMs`, never the wall clock.
+  - Use it only against a seller that materializes subscription obligations in its ledger.
+- `handleAuthenticatedPrincipalChanged` calls `onPrincipalChanged` (for example to re-read `get_principal` and `accounts_unauthorized` and replace the roster) and then reconciles every account of the consumer scope.
+  - It drops a redelivery with an already seen `idempotency_key`.
+  - Notifications that arrive during a run share one trailing run.
+- `createReportingSubscriptionEngineStateStoreV1({ store })` persists the engine's sharded state on any `AdcpStateStore`: one CAS document per principal and one per (principal, account), listed per tenant. With `PostgresStateStore` it is durable and needs no migration beyond `ADCP_STATE_MIGRATION`. Subscription version history stays in the principal row and is never pruned, so `prior_versions` remain answerable for retained obligations.

.changeset/reporting-subscription-coverage.md

@@ -0,0 +1,13 @@
+---
+'@adcp/sdk': minor
+---
+
+Add the buyer-computable coverage rule for AdCP 3.3 principal-level reporting subscriptions (experimental `media_buy.reporting_subscriptions`, #3504). `expectedSubscriptionPeriods(input)`, exported from `@adcp/sdk/reporting/consumer` and `@adcp/sdk/reporting/ledger`, is a pure function of the buyer's own records: subscription versions with their `accepted_at`, visible confirmed buys and their earlier flight values, the account's grants and timezone, the seller's published offerings (matching reads each offering's `standard_dimensions` and `unmapped_dimensions`), the readback's `inactive_intervals`, and the published `subscription_coverage` exceptions, including per-offering `gaps[]` and `timezone_cutovers[]` with `previous_timezone`. It returns every owed (buy, offering, period), and `groupExpectedSubscriptionPeriodsV1` groups them into the obligations that must carry them. It implements the start rule of adcp#8593 (the first boundary at or after the later of `accepted_at` and `authorized_at`, and every period ending after the buy's `confirmed_at`, so the period in which a buy is confirmed is owed in full), flight overlap as of each period's resolution, unclipped periods, the single cutover rule for new versions, deactivation, resolution changes and account timezone changes, revocation and re-grant with and without `backfill_on_regrant`, and exceptions that only remove periods.
+
+Also exported: `createReportingPeriodCalendarV1`, the normative `period_generation` calendar for `utc`, `account_timezone`, `source_timezone` and `billing_cycle` schedules; `resolveReportingSubscriptionOfferingsV1` for `exact`, `finest` and `all` selector resolution with byte-order ties; `reportingSubscriptionScopeIncludesV1`; and `reportingConfigurationCapabilitiesV1`, which builds `configuration_tasks`, the deprecated `configuration_task` and the `subscriptions` block consistently.
+
+`installConfiguration` now throws a typed `ReportingConfigurationImmutableError` (`code: 'REPORTING_CONFIGURATION_IMMUTABLE'`, with `accountId`, `deliveryConfigId` and `deliveryConfigVersion`) when an existing generation is reinstalled with different content. The message is unchanged; use `isReportingConfigurationImmutableError` instead of matching it.
+
+The rules follow adcontextprotocol/adcp#8585. The fields it added after 3.3.0-beta.1 (`standard_dimensions`, `unmapped_dimensions`, `inactive_intervals`, `previous_timezone`, and per-offering `offering_id` on gaps and cutovers) are hand-modeled until 3.3.0-beta.2 ships. The cross-SDK parity table is `test/fixtures/reporting-subscriptions/coverage-cases.json`.
+
+Sub-daily periods under a local alignment restart at each local midnight on wall-clock multiples (adcontextprotocol/adcp#8588). A gap yields no boundary and a fold one per offset, and the duration must divide 24 hours; mixed date and time components are refused. Calendars gain `next()`. An empty flight overlaps nothing, and a cutover carries the outgoing stretch's own start, so two cutovers in one period never owe a period twice. A billing anchor inside a DST fold is interval zero itself. A wire `authorized_at` equal to the chain start continues the chain. The walk has an iteration budget. The SDK's schema validation accepts dimension values outside the published `enums/reporting-dimension.json` vocabulary, which is extensible.

.changeset/reporting-subscription-delivery.md

@@ -0,0 +1,18 @@
+---
+'@adcp/sdk': minor
+'@adcp/reporting-storage': minor
+---
+
+Managed delivery for AdCP 3.3 subscription obligations (experimental `media_buy.reporting_subscriptions`, #3504).
+
+- `reportingSubscriptions.bindManagedGeneration` binds a managed subscription generation to its destination before the generation's first obligation is written. The planner calls it through `planSubscriptionObligations({ bindGeneration })`. A rejection writes nothing, and the next cycle tries again. A subscription that resolves a managed offering without a binding composition fails to plan.
+- Every row of a subscription revision carries `account_id`. It is stamped before the revision is bound, and a row naming another account is refused. Account revisions are unchanged.
+- `ReportingLedgerSubscriberV1.principal` scopes status subscribers: a subscription obligation's transitions reach only its owning principal.
+- The engine gains `isAuthorized(principal, accountId)`, and `frozenOwedSets` versions carry the frozen `destination_method`. `withReportingSubscriptionCoverageV1` is exported for compositions.
+- `@adcp/reporting-storage`:
+  - `createPostgresReliableReportingProductionService` delivers managed subscription obligations. Pass the principal runtime as `reportingSubscriptions.principal`; the engine must have `isAuthorized`.
+  - `createReportingSubscriptionManagedBindingV1` resolves the owner's current destination generation, authorizes it per account (`ensureDestinationAuthorization`), and installs a binding that freezes the version's `path_template`.
+  - The managed worker passes the expanded `delivery_path` to adapters. It re-checks the owner's account authority before delivering and before settling, and releases a lost claim with `holdMaterialization` without failing it. Reads are scoped with `resolveSubscriptionPrincipal`.
+  - `REPORTING_MANAGED_DELIVERY_MIGRATION` drops the three-column `adcp_reporting_managed_bindings` key, found by its columns, so bindings are keyed by their Core configuration. It is additive and idempotent.
+  - `reportingObjectWriteName` takes an optional delivery path that sits inside the generation prefix, and `isReportingObjectWriteName` recognizes it. The GCS adapter writes there, and status reads scope to the owner.
+  - Notification activity for a subscription obligation is fanned out only to its owning principal.

.changeset/reporting-subscription-dx-advanced.md

@@ -0,0 +1,10 @@
+---
+'@adcp/sdk': minor
+'@adcp/reporting-storage': minor
+---
+
+Reporting subscriptions (experimental `media_buy.reporting_subscriptions`, AdCP 3.3): the low-level building blocks move to a new `@adcp/sdk/reporting/advanced` subpath, tagged `@experimental`.
+
+- `@adcp/sdk/reporting/advanced` exports the coverage engine (`createReportingSubscriptionEngineV1`) and its stores (`createInMemoryReportingSubscriptionEngineStoreV1`, `createReportingSubscriptionEngineStateStoreV1`), the coverage function (`expectedSubscriptionPeriods`, `groupExpectedSubscriptionPeriodsV1`, `reportingSubscriptionCoverageGrantedV1`), the period calendar, offering selection, the capability builder (`reportingConfigurationCapabilitiesV1`), the consumer bridge (`reportingSubscriptionVersionRecordsV1`, `subscriptionExpectedReportingPeriodsV1`), and the service's subscription hooks (`ReliableReportingSubscriptionsOptionsV1` and its input types, `withReportingSubscriptionCoverageV1`).
+- `@adcp/sdk/reporting/service`, `/consumer` and `/ledger` no longer re-export them. Change the import path; the symbols are unchanged. The `reportingSubscriptions` option on `createReliableReportingService` is unchanged.
+- `@adcp/reporting-storage` imports `withReportingSubscriptionCoverageV1` and `ReliableReportingSubscriptionBindingInputV1` from the new subpath, so it needs an `@adcp/sdk` that has it.

.changeset/reporting-subscription-dx-buyer-facade.md

@@ -0,0 +1,14 @@
+---
+'@adcp/sdk': minor
+---
+
+Reporting subscriptions (experimental `media_buy.reporting_subscriptions`, AdCP 3.3): the buyer write facade and the raw `syncPrincipal` guard.
+
+- **`client.reporting`** (`ReportingClient`, on `AgentClient` and `SingleAgentClient`) offers `subscribe`, `unsubscribe`, `replaceSubscriptions`, `listSubscriptions` and `preview`.
+  - Writes are patch-shaped over the replace-shaped wire: other entries are kept byte for byte.
+  - `subscription_version` is optional. It is kept for in-place changes and bumped on a semantic change.
+  - `registerDestination` upserts a destination in the same write.
+- **Pre-dispatch refusals.** A `ReportingSubscriptionError` with `dispatched: false` is thrown for: an implicit scope, an unregistered destination, a missing `{account_id}`, `SUBSCRIPTION_ID_CLASH`, `SUBSCRIPTION_OPERATOR_SCOPE_REQUIRED` and `SUBSCRIPTION_SELECTOR_UNMATCHED` (with `nearest`).
+- **Retries and readback.** On `CONFLICT` the facade re-reads, re-merges and retries with a fresh key (3 attempts), then throws `SUBSCRIPTION_CONFLICT_EXHAUSTED`. A transport failure retries the same key and body. The readback is verified, and a mismatch throws `SUBSCRIPTION_READBACK_MISMATCH`. Names follow the Python SDK's `ReportingClient`; the preview result type is `SubscriptionPreviewResult`.
+- **Raw `syncPrincipal` guard.** A raw `client.syncPrincipal` that submits `reporting_subscriptions` or `reporting_destinations` reads the principal once. It refuses, before sending, a write that would deactivate a subscription (`SUBSCRIPTION_WOULD_DEACTIVATE`) or revoke a destination (`DESTINATION_WOULD_REVOKE`) unless you pass `allowDeactivation` / `allowRevocation`. Dry runs, the lifecycle helpers and storyboard runs are not guarded.
+- `guardSyncPrincipal` is exported, and `ReportingSubscriptionError` accepts a seller's wire code or a local `INVALID_REQUEST`.

.changeset/reporting-subscription-dx-errors.md

@@ -0,0 +1,10 @@
+---
+'@adcp/sdk': minor
+---
+
+Typed reporting-subscription errors (experimental `media_buy.reporting_subscriptions`, AdCP 3.3), using the shared error vocabulary (`error-codes.json` in the spec repository).
+
+- `ReportingSubscriptionError` (package root) carries `code`, `recovery` and the vector context fields (`wouldDeactivate`, `wouldRevoke`, `deliveryConfigId`, `accountId`, `nearest`, `readback`). The five refusal codes the SDK raises before sending always carry `dispatched: false`. Its codes are `SUBSCRIPTION_WOULD_DEACTIVATE`, `DESTINATION_WOULD_REVOKE`, `SUBSCRIPTION_ID_CLASH`, `SUBSCRIPTION_OPERATOR_SCOPE_REQUIRED`, `SUBSCRIPTION_SELECTOR_UNMATCHED`, `SUBSCRIPTION_CONFLICT_EXHAUSTED` and `SUBSCRIPTION_READBACK_MISMATCH`. `syncReportingSubscriptionsV1` throws it for its deactivation guard (with `wouldDeactivate`), for conflict exhaustion and for a readback mismatch (with `readback`), where it used to throw `PrincipalLifecycleError`.
+- `PrincipalLifecycleError` is now an `ADCPError`, with `code` (`PRINCIPAL_CONFLICT_EXHAUSTED`, `PRINCIPAL_TRANSPORT_FAILED`, `PRINCIPAL_SETUP_TIMEOUT`, ...), `recovery`, and `dispatched: false` when no `sync_principal` write was sent. `applied` is renamed `appliedResponse` so it can't be read as a boolean next to `dispatched`. `applied` stays as a deprecated alias, and the constructor still accepts it.
+- `CoverageInputError` (`COVERAGE_INPUT_INCOMPLETE`, `COVERAGE_INPUT_INVALID`, `COVERAGE_BUDGET_EXCEEDED`, with a `detail` such as `missing_account_timezone` or `invalid_period_duration`) replaces the `TypeError` and `RangeError` the coverage function and the period calendar threw.
+- The engine throws `ReportingSubscriptionEngineError` (`SUBSCRIPTION_STATE_CONFLICT`, `SUBSCRIPTION_STATE_CORRUPT`, `SUBSCRIPTION_ROSTER_INCOMPLETE`, `SUBSCRIPTION_HOST_FACT_INVALID`) at run time, and `PlatformConfigError` for configuration mistakes. `PlatformConfigError` gains `code` (`PLATFORM_CONFIG_INVALID` by default; `REPORTING_STORAGE_NOT_DURABLE` and `SUBSCRIPTIONS_REQUIRE_STANDARD_DIMENSIONS` where they apply), `configField` and `recovery: 'correctable'`.

.changeset/reporting-subscription-dx-exclusions.md

@@ -0,0 +1,7 @@
+---
+'@adcp/sdk': minor
+---
+
+Reporting subscriptions (experimental `media_buy.reporting_subscriptions`, AdCP 3.3): the engine writes per-offering exclusions.
+
+When the offerings a condition covers have different period boundaries, the engine writes one `excluded[]` entry per offering, with `offering_id` and that offering's own cutover instants. This covers `capacity`, `excluded_by_buyer`, `action_required` and `overridden` across calendars, and a buy's `offering_unsupported` after a resolution change. Before, it wrote one account-wide entry cut at the latest end. One calendar, or several with the same schedule, still gets a single entry. A per-offering entry closes at its own offering's cutover. Callers served a release whose `excluded[]` has no `offering_id` get the entries folded back into one entry cut at the latest instant, as before.

.changeset/reporting-subscription-dx-grants.md

@@ -0,0 +1,10 @@
+---
+'@adcp/sdk': minor
+---
+
+Reporting subscriptions (experimental `media_buy.reporting_subscriptions`, AdCP 3.3): the grant journal is the one source of `authorized_at`.
+
+- **Served value.** With the managed `subscriptions` block, the service serves the journal's `authorization.authorized_at` on `list_accounts` and `sync_accounts` to callers holding subscriptions. The derived roster reads the same value, so buyers read what coverage uses.
+- **Journal rules.** A host value is adopted the first time a chain is observed, and an omitted one is stamped. A value that moves an open chain earlier is refused and logged as `authorized_at_regressed`. A re-grant inside `status_retention_days` continues the chain; a later one starts a new chain.
+- **`service.grants.changed({ principal, accountId, at, authorized, allowedTasks?, timezone?, operator? })`** pushes a grant change for an exact instant.
+- **Engine.** `engine.observeGrants(principal, observations)` exposes the journal (`@adcp/sdk/reporting/advanced`). `authorizationChanged` applies the chain rule to pushed re-grants. `resolveRevocationInstant` is optional: without it, a revocation is dated when it was observed.

.changeset/reporting-subscription-dx-managed.md

@@ -0,0 +1,19 @@
+---
+'@adcp/sdk': minor
+'@adcp/reporting-storage': minor
+---
+
+Reporting subscriptions (experimental `media_buy.reporting_subscriptions`, AdCP 3.3): the managed seller path.
+
+- `createReliableReportingService({ subscriptions: SubscriptionOptions })` enables the feature without assembling the engine by hand. The service:
+  - builds the coverage engine;
+  - installs the `reporting_subscriptions` section on the principal runtime (`subscriptions.principals`, created without `reportingSubscriptions`);
+  - fills in `capabilities.principal` in `install()`;
+  - reconciles a principal after each `sync_principal` write that submits subscriptions (`reconcileOnWrite`, on by default);
+  - sweeps every subscribed principal at the start of each `runCycle`.
+- **Derived inputs.** The roster comes from the platform's `accounts.list` and the buys from `sales.getMediaBuys`, read under the principal's identity. `accounts`, `buys`, `buyOfferings`, `accountDeliveryConfigs`, `endAccountConfigs`, `isPeriodDelivered` and `resolvePrincipal` override them. `configure` is required.
+- **Failures.** A roster that can't be read is a `PlatformConfigError` coded `SUBSCRIPTION_ROSTER_UNAVAILABLE`. Reconcile and planning failures are returned in `runCycle`'s `subscriptionPlanningFailures` and passed to `planningErrorHandler`; they are never thrown as an `AggregateError`.
+- **Options.** The names follow the Python SDK's `SubscriptionOptions`. The advanced block with your own `engine` still works, as before.
+- **Principal runtime.** The runtime gains `installReportingSubscriptions` (internal) and `PrincipalReportingSubscriptionSupport.onApplied`. Its `capabilities` reflects a section installed later.
+- **Service.** `service.subscriptionWiring` exposes the resolved wiring to compositions.
+- **`@adcp/reporting-storage`.** The production service accepts the managed block.

.changeset/reporting-subscription-dx-naming.md

@@ -0,0 +1,15 @@
+---
+'@adcp/sdk': minor
+'@adcp/reporting-storage': minor
+---
+
+Reporting subscriptions (experimental `media_buy.reporting_subscriptions`, AdCP 3.3): names frozen before beta.3. Every old name stays as a deprecated alias for one beta.
+
+- `PrincipalRef { tenantId, principalId }` (package root, `@adcp/sdk/server`, `/reporting/advanced`, `/reporting/ledger`) is the one principal identity type. `PrincipalStoreScope` and `ReportingLedgerSubscriptionPrincipalV1` are deprecated aliases.
+- "Owed" is the one word for what a seller must deliver (`@adcp/sdk/reporting/advanced`):
+  - `expectedSubscriptionPeriods` → `owedSubscriptionPeriodsV1`, which also gains the `V1` suffix the module's other low-level symbols carry;
+  - `groupExpectedSubscriptionPeriodsV1` → `groupOwedSubscriptionPeriodsV1`;
+  - `ExpectedSubscriptionPeriodV1`, `ExpectedSubscriptionObligationV1` and `ExpectedSubscriptionPeriodsInputV1` → `OwedSubscriptionPeriodV1`, `OwedSubscriptionObligationV1` and `OwedSubscriptionPeriodsInputV1`;
+  - `subscriptionExpectedReportingPeriodsV1` → `toExpectedReportingPeriodsV1`, which keeps "expected" because it feeds the consumer's `ExpectedReportingPeriod`.
+- The principal runtime's `recordReportingSubscriptionCoverage` → `recordSubscriptionReadback`, because it writes readback lists, not `subscription_coverage`. The engine's `listPrincipals` → `listSubscriptionPrincipals`, which matches the service hook it feeds.
+- `createReliableReportingService({ subscriptions })` and `createPostgresReliableReportingProductionService({ subscriptions })` replace `reportingSubscriptions`, which stays as a deprecated alias. Passing both is a `PlatformConfigError`.