@adcp/sdk 16.0.0-beta.3 → 16.0.0-beta.4

package/docs/guides/REPORTING-OPERATIONS.md

@@ -5,7 +5,7 @@ consumer runtime. Reliable Reporting controls evidence used for billing and
 large media-spend decisions. Treat its PostgreSQL state, destination objects,
 signing keys, and authentication registry as financial infrastructure.
 
-> **Stability:** the storage subpaths this runbook operates are experimental. Pin `@adcp/sdk` with `~` and read each minor's changeset before upgrading. See the [Reliable Reporting stability policy](REPORTING-STABILITY.md).
+> **Stability:** the storage this runbook operates lives in `@adcp/reporting-storage`, which is pre-1.0 and experimental. Pin it with `~` (for example `~0.1.0`) and read each minor's changeset before upgrading. See the [Reliable Reporting stability policy](REPORTING-STABILITY.md).
 
 ## Production topology
 
@@ -80,7 +80,8 @@ Each of these features is opt-in and additive. Enable them one at a time on a
 running deployment. See the [ledger guide](REPORTING-LEDGER.md#row-storage)
 for configuration details.
 
-Running Core only, without the production service? Pass `maintenance` to
+Running Core only, without the production service? Pass `maintenance:
+reportingLedgerMaintenance({ ... })` (from `@adcp/reporting-storage`) to
 `createReliableReportingService` so its scheduler (or `runMaintenance()`) does
 the retention, change-feed pruning and abandoned-upload sweeps the production
 service runs for you. See
@@ -143,6 +144,58 @@ service runs for you. See
    for the rule and what it keeps. Compaction cannot be undone; backups hold
    any longer evidence.
 
+8. **Orphaned object collection (optional).** The intent sweep deletes only
+   what an intent lists. It cannot see an upload whose `PUT` succeeded before the
+   intent recorded it, an intent for a binding no running host configures, or an
+   intent lost to a database restore, and a bucket lifecycle rule cannot tell
+   those objects from committed ones. Enable `orphanCollection`
+   (`maintenance.orphanCollection` on the Core-only service) to list each
+   configured object binding under `{prefix}/{namespace_key}/` and delete what
+   nothing names. Roll it out in this order:
+   1. Run it with `dryRun: true` and read `candidates` in the
+      `orphan object collection` task result. Confirm they are objects you
+      expect to lose.
+   2. Enable it for real, with `acknowledgeExclusiveNamespace: true` (see
+      below), a modest `limit` (objects examined per binding per pass, default
+      1000) and one host.
+
+   It is built for a long period: a listing that does not finish within `limit`
+   continues on the next pass, and a finished one rests for `intervalSeconds`
+   (default one day) before the next starts. That position lives in the process,
+   so a restart begins a new listing; the cost is bounded by `limit` per pass
+   either way. Reduce `limit`, or lengthen `intervalSeconds`, to spend fewer list
+   requests.
+
+   An object is deleted only when all of these hold: its key is a `.jsonl` or
+   `.jsonl.gz` object under the binding's owned prefix; it was written more than
+   `minAgeSeconds` ago (default 7 days, never less than 1 day, which must stay
+   well above the write deadline plus intent expiry); no row set that is not yet
+   `pruned` has a chunk at that key and no write intent lists it, at any version;
+   and, under the per-object advisory lock every other delete takes, no `live` or
+   `unavailable` row set references that exact version and no open intent
+   created it, checked under every binding because two bindings can share a
+   bucket and prefix (a retired binding kept `readOnly` next to its successor).
+   `readOnly` bindings are skipped unless `includeReadOnly: true`. A binding
+   whose provider has no `list` is reported as `unsupported` (and as a
+   maintenance warning), never silently skipped. Everything under the owned prefix
+   with a row-object key counts as written by this SDK, so do not store other
+   `.jsonl` files there.
+
+   **Run it only against the ledger database that owns the namespace.** The
+   namespace key comes from the database's installation identity. A clone or
+   point-in-time copy of that database that still points at the same bucket
+   shares the key, and its collector would delete the objects of every row set
+   the original wrote after the copy was taken, because the copy has never heard
+   of them. The age threshold does not protect against that, which is why a real
+   (not dry) pass needs `acknowledgeExclusiveNamespace: true`: it is your statement
+   that this database is the only owner. A clone made by copying the deployment
+   copies the flag too, so the flag does not protect it: remove it, or the whole
+   option, from every copy. Disable the option on clones, and after
+   restoring a database in place expect the collector to delete the objects of the
+   row sets the restore lost, which is its purpose.
+   The cost grows with bucket size: one listing request per page, plus one
+   database query per page and one transaction per deleted object.
+
 Alert on these row-storage signals:
 
 - `ROWS_INTEGRITY_FAILED` or `ROWS_UNAVAILABLE` from reads. These are never
@@ -154,6 +207,14 @@ Alert on these row-storage signals:
   host does not configure, and `overdue` (expired more than 24 hours ago, still
   unswept) means no host is handling them and their objects are leaking. The
   maintenance helper reports both through `onError`.
+- The `orphan object collection` task reporting `failed` or `unsupported`
+  bindings (their provider cannot list, so nothing there is collected). A listing
+  that fails is retried from the page that failed (or from the start, if it was
+  the first page of a resumed listing). A delete that fails is counted and the
+  pass moves on, so one stuck object cannot hold up the rest; it is tried again on
+  the next full listing. `referenced` and
+  `tooYoung` are normal; a `foreign` count means the prefix holds objects this
+  SDK did not write as row objects, which it leaves alone.
 - The `snapshot compaction` task reporting `failed` revisions. Provider deletes
   are failing; the revisions stay `pruning` (reads already answer not-found) and
   the next pass resumes them.
@@ -328,7 +389,7 @@ For complete GCS file-transfer delivery, private contracts and scoped buyer read
 
 ## Live GCP validation
 
-`scripts/validate-reporting-gcp.mjs` runs the built SDK against a real BigQuery
+`packages/reporting-storage/scripts/validate-reporting-gcp.mjs` (`npm run validate:reporting-gcp`) runs the built `@adcp/reporting-storage` against a real BigQuery
 project and a real GCS bucket. The in-memory doubles in the test suite cannot
 prove how BigQuery names jobs, where it stores load options, or what a real
 bucket policy looks like; this script does. It is not published with the
@@ -336,7 +397,7 @@ package, so run it from a repository checkout.
 
 What it checks:
 
-- **BigQuery warehouse sink** (`@adcp/sdk/reporting/bigquery`). It applies the
+- **BigQuery warehouse sink** (`@adcp/reporting-storage/bigquery`). It applies the
   ledger migrations into fresh PostgreSQL schemas, commits revisions, creates a
   uniquely named dataset in the destination project from `defaultTablesSql` and
   `currentRowsViewSql`, and runs the sink. It verifies row and revision counts
@@ -372,7 +433,7 @@ What it checks:
   `GCP_BQ_PROJECT`. Load jobs are then created in the destination project, and
   the crash replay fails if the "job already exists" status check looks in the
   client's default project instead.
-- **GCS row provider** (`@adcp/sdk/reporting/gcs`). It prints the bucket policy,
+- **GCS row provider** (`@adcp/reporting-storage/gcs`). It prints the bucket policy,
   runs the provider probe (uniform bucket-level access, public access
   prevention, lifecycle rules) and `runReportingRowObjectProviderConformanceV1`,
   then commits a revision through an object binding on the bucket and reads it

package/docs/guides/REPORTING-STABILITY.md

@@ -1,76 +1,80 @@
 # Reliable Reporting stability policy
 
-The Reliable Reporting storage surface is **experimental**. It is new, it has not yet run in production at an adopter, and its shape is still being settled by real use. Marking it experimental lets breaking changes there ship in minor releases, with notice, instead of forcing a major release of the whole SDK.
+The Reliable Reporting storage surface is **experimental**. It is new, it has not yet run in production at an adopter, and its shape is still being settled by real use. It ships as its own package, `@adcp/reporting-storage`, on its own version line, so a breaking change there is a minor release of that package and never forces a major release of `@adcp/sdk`.
 
-This follows how the AdCP protocol treats experimental surfaces (`x-status: experimental` in the schemas, with advance notice of breaking changes).
+This follows how the AdCP protocol treats experimental surfaces (`x-status: experimental` in the schemas, with advance notice of breaking changes), and how other SDKs ship storage (Auth.js `@auth/pg-adapter`, LangGraph's checkpoint packages, OpenTelemetry exporters). The Python SDK is making the same split (adcp-client-python#1510).
 
 ## What is experimental
 
-An export is experimental when its TSDoc carries an `@experimental` tag that links to this page. Editors show the tag on hover, and some mark the symbol as unstable.
+**Everything exported by `@adcp/reporting-storage`.** The package is pre-1.0 (`0.x`), and each export carries an `@experimental` TSDoc tag that links to this page. Editors show the tag on hover, and some mark the symbol as unstable.
 
-| Subpath                        | Status                                                                      |
-| ------------------------------ | --------------------------------------------------------------------------- |
-| `@adcp/sdk/reporting/gcs`      | Experimental (every export)                                                 |
-| `@adcp/sdk/reporting/s3`       | Experimental (every export)                                                 |
-| `@adcp/sdk/reporting/azure`    | Experimental (every export)                                                 |
-| `@adcp/sdk/reporting/bigquery` | Experimental (every export)                                                 |
-| `@adcp/sdk/reporting/ledger`   | Partly experimental (see below)                                             |
-| `@adcp/sdk/reporting/service`  | Partly experimental: retention, compaction and change-feed maintenance only |
+| Subpath                                 | Holds                                                                                                              |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `@adcp/reporting-storage`               | the PostgreSQL ledger store (`PostgresReportingLedgerStore`), its migrations, `sweepExpiredReportingLedgerState`, row storage (`ReportingRowStorageV1`, row bindings, the provider contract and conformance suite, the filesystem provider, the row-storage migration and probe), object writes, the host change feed (`REPORTING_LEDGER_CHANGES_MIGRATION`, change records and cursors), and ledger maintenance (retention, compaction, orphan collection, change-feed pruning, `reportingLedgerMaintenance`) |
+| `@adcp/reporting-storage/managed`       | the managed-delivery runtime, `PostgresReportingManagedDeliveryStore`, the adapter contract and the adapter router |
+| `@adcp/reporting-storage/notifications` | notification activity stores, checkpoints and runtime                                                              |
+| `@adcp/reporting-storage/service`       | `createPostgresReliableReportingProductionService`                                                                 |
+| `@adcp/reporting-storage/gcs`           | the GCS write fence, reader, managed-delivery adapter and row-object provider                                      |
+| `@adcp/reporting-storage/s3`            | the S3 row-object provider                                                                                         |
+| `@adcp/reporting-storage/azure`         | the Azure Blob row-object provider                                                                                 |
+| `@adcp/reporting-storage/bigquery`      | the BigQuery warehouse sink                                                                                        |
 
-Within `@adcp/sdk/reporting/ledger`, the experimental exports are:
+**The storage interfaces in `@adcp/sdk`.** The contract the package implements stays in the SDK, and it changes together with the package, so it is experimental too: the store, transaction, lease, row-read and revision-metadata interfaces in `@adcp/sdk/reporting/ledger` (`ReportingLedgerStore` and the types it uses), `ReportingReceiptSyncStoreV1`, the store-contract error classes (`ReportingLedgerLeaseLostError`, `ReportingLedgerPeriodRetiredError`, `ReportingLedgerContinuityError`) and the row-storage error types. Their TSDoc carries the `@experimental` tag. A breaking change to one ships as a minor of `@adcp/sdk` together with a matching minor of `@adcp/reporting-storage`, and the changesets say which pair to install.
 
-- the PostgreSQL ledger store (`PostgresReportingLedgerStore`), its migrations and errors, and `sweepExpiredReportingLedgerState`;
-- row storage (`ReportingRowStorageV1`, row bindings, row encoding, the row-storage migration and probe, and row-store errors) and object writes;
-- the host change feed (`REPORTING_LEDGER_CHANGES_MIGRATION`, change records and cursors);
-- managed delivery (the runtime, the store, the adapter contract, the adapter router and the PostgreSQL store);
-- notification activity stores and checkpoints;
-- the store, transaction, lease and row-read interfaces in `ledger/types`.
-
-Within `@adcp/sdk/reporting/service`, the experimental exports are `ReportingRetentionOptionsV1`, `ReportingCompactionOptionsV1`, `ReportingChangeFeedMaintenanceOptionsV1`, `runReportingLedgerMaintenance` and the related maintenance types and error.
+**Storage-facing building blocks in `@adcp/sdk`.** A few exports exist so a store can be written against public API only, and they are covered by the same policy even where their TSDoc is silent: the schedule, instant and evidence helpers on `@adcp/sdk/reporting/ledger` (`compareReportingInstants`, `reportingPeriodDate`, `reportingPeriodSchedule`, `isFrozenCalendarRulesMismatch`, the receipt and verification evidence guards, `isWellFormedUnicodeString`, `getReportingDeliveryOfferingValidatorV1`), and the scheduler primitives and `REPORTING_MANAGED_DELIVERY_COMPOSITION_V1` on `@adcp/sdk/reporting/service`. Application code should not depend on them.
 
 ### Not experimental
 
-These follow normal semver. A breaking change to them ships in a major release.
+These follow normal semver. A breaking change to them ships in a major release of `@adcp/sdk`.
 
 - The protocol-facing handlers: `createReportingDeliveryHandler`, `createReportingStatusHandler`, `createSyncReportingStatusHandler`, `createSyncReportingReceiptsHandler`, and the status-ingest request and response schemas.
 - `createReportingProducer`, `assertSupportedReportingAuthoritativeParty` and `UnsupportedReportingFeatureError`.
-- The health, coverage, lifecycle, schedule and consumer-status-identity helpers in `@adcp/sdk/reporting/ledger`.
-- `createReliableReportingService`, `createPostgresReliableReportingProductionService` and the service conformance runner in `@adcp/sdk/reporting/service`.
+- The health, coverage, lifecycle, schedule and consumer-status-identity helpers in `@adcp/sdk/reporting/ledger`, and the canonical row encoding and digests (`row-encoding`) with their golden fixtures.
+- `createReliableReportingService`, its `maintenance` hook and the service conformance runner in `@adcp/sdk/reporting/service`.
 - `@adcp/sdk/reporting/consumer` (buyer reconciliation and worker) and `@adcp/sdk/reporting/source` (source contract and executor). They are separate subpaths with their own `V1` contract suffixes and are not covered by this policy.
 
 If you are unsure about a symbol, read its TSDoc. An `@experimental` tag means it is covered. No tag means it is not.
 
 ## What "experimental" means
 
-- **Breaking changes may ship in minor releases.** That covers signatures, option names, stored field and column names, migrations, and defaults in the experimental exports.
+- **Breaking changes may ship in minor releases of `@adcp/reporting-storage`.** That covers signatures, option names, stored field and column names, migrations, and defaults. While the package is `0.x`, a minor bump (`0.1` to `0.2`) is the one that may break.
 - **Every such change is announced.** The changeset describes the break and includes a migration note, and the release notes carry it. Larger changes also get a `docs/migration-*.md` walkthrough.
-- **The wire protocol is not affected.** Buyer-visible behavior these exports implement (reporting delivery, `revision_content_sha256`, status, receipts and so on) follows AdCP's own versioning, not this policy. A change to the SDK's storage layout does not change what a buyer sees.
+- **The wire protocol is not affected.** Buyer-visible behavior the package implements (reporting delivery, `revision_content_sha256`, status, receipts and so on) follows AdCP's own versioning, not this policy. A change to the storage layout does not change what a buyer sees.
 - **Security and correctness fixes are not held back.** If a fix needs a breaking change, it ships in a minor.
 
+## How the two packages line up
+
+`@adcp/reporting-storage` declares `@adcp/sdk` as a **peer dependency** (`^16.0.0-beta.0` while SDK 16 is in beta), not a dependency. The store, its errors and the handlers share types and symbol-keyed guards, so the host must hold one copy of `@adcp/sdk`. A change to a storage interface in the SDK ships with a matching storage release; the changeset for each says which pair to install. The cloud SDKs (`@aws-sdk/client-s3`, `@azure/storage-blob`, `@google-cloud/storage`) are optional peers of the storage package. `@adcp/sdk` does not import `@adcp/reporting-storage`, and a test and a lint rule keep it that way.
+
 ## How to pin
 
-Adopters of the experimental subpaths should not use a caret range, which accepts every future minor.
+Pin the storage package with a tilde range. A caret range on a `0.x` version already stops at the next minor, but `~` states the intent and survives the move to `1.0`.
 
 ```json
 {
   "dependencies": {
-    "@adcp/sdk": "~16.0.0"
+    "@adcp/sdk": "^16.0.0-beta.0",
+    "@adcp/reporting-storage": "~0.1.0-beta.0"
   }
 }
 ```
 
-- `~16.0.0` takes patches only (recommended).
-- An exact version (`"16.0.0"`) is stricter still.
+Those are the beta pins. A prerelease range such as `~0.1.0` does not match `0.1.0-beta.0`, so use the `-beta.0` form until stable releases exist, then move to `^16.0.0` and `~0.1.0`.
+
+- `~0.1.0` (after the first stable release) takes patches only (recommended).
+- An exact version (`"0.1.0-beta.0"`) is stricter still.
 - Read the changelog before widening to a new minor, and apply any migration it names.
 
-If you use only the stable surfaces, a caret range is fine as usual.
+`@adcp/sdk` itself can use a caret range as usual, because the SDK's own surface follows semver. While SDK 16 is in beta, install both packages with the `beta` dist-tag (`npm install @adcp/sdk@beta @adcp/reporting-storage@beta`) until stable releases exist.
 
 ## Migrations
 
-Database migrations exported from experimental subpaths (`REPORTING_LEDGER_MIGRATION`, `REPORTING_ROW_STORAGE_MIGRATION` and the others) stay idempotent where practical, and a changeset says when you must re-apply one. See [Reliable Reporting production operations](REPORTING-OPERATIONS.md) and the [ledger guide](REPORTING-LEDGER.md).
+Database migrations exported by `@adcp/reporting-storage` (`REPORTING_LEDGER_MIGRATION`, `REPORTING_ROW_STORAGE_MIGRATION` and the others) stay idempotent where practical, and a changeset says when you must re-apply one. See [Reliable Reporting production operations](REPORTING-OPERATIONS.md) and the [ledger guide](REPORTING-LEDGER.md).
+
+Coming from the single-package layout (`@adcp/sdk/reporting/ledger`, `/gcs`, `/s3`, `/azure`, `/bigquery`)? See [Reliable Reporting storage moved to `@adcp/reporting-storage`](../migration-reporting-storage-package.md).
 
 ## When this will change
 
-The surface is expected to stabilize after the first production adopter runs on SDK 16 stable. At that point the `@experimental` tags are removed in a minor release with a changelog note, and breaking changes need a major release from then on.
+The surface is expected to stabilize after the first production adopter runs on SDK 16 stable. At that point `@adcp/reporting-storage` moves to `1.0.0` and the `@experimental` tags are removed in that release with a changelog note. Breaking changes need a major release from then on.
 
 Related: [Seller reporting ledger](REPORTING-LEDGER.md), [Reliable Reporting production operations](REPORTING-OPERATIONS.md).

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
-> Generated at: 2026-10-15
-> Library: @adcp/sdk v16.0.0-beta.3
+> Generated at: 2026-10-16
+> Library: @adcp/sdk v16.0.0-beta.4
 > AdCP major version: 3
 > Canonical URL: https://adcontextprotocol.github.io/adcp-client/llms.txt
 > Note: the `Library` stamp reflects the package.json version at doc-generation time. The narrative below describes the surface that lands on the next-published minor — including any 6.7 helpers documented here ahead of the release tag.
@@ -2126,6 +2126,7 @@ These docs are available locally in the repo and hosted at https://adcontextprot
 | Seller quick start (AdCP 3.2) | docs/guides/SELLER-QUICKSTART-3.2.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/SELLER-QUICKSTART-3.2.md) |
 | Production durability checklist | docs/guides/PRODUCTION-DURABILITY.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/PRODUCTION-DURABILITY.md) |
 | Persistent notification subscriptions | docs/guides/PERSISTENT-NOTIFICATION-RUNTIME.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/PERSISTENT-NOTIFICATION-RUNTIME.md) |
+| Reliable Reporting storage moved to @adcp/reporting-storage (SDK 16 beta) | docs/migration-reporting-storage-package.md | [link](https://adcontextprotocol.github.io/adcp-client/migration-reporting-storage-package.md) |
 | Migrating SDK 13 → 14 | docs/migration-13-to-14.md | [link](https://adcontextprotocol.github.io/adcp-client/migration-13-to-14.md) |
 | Getting started / install | docs/getting-started.md | [link](https://adcontextprotocol.github.io/adcp-client/getting-started.md) |
 | Build a server-side agent | docs/guides/BUILD-AN-AGENT.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/BUILD-AN-AGENT.md) |
@@ -2143,7 +2144,7 @@ These docs are available locally in the repo and hosted at https://adcontextprot
 | Reporting ledger cutover from custom tables | docs/guides/REPORTING-LEDGER-CUTOVER.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/REPORTING-LEDGER-CUTOVER.md) |
 | Buyer reporting reconciliation | docs/guides/REPORTING-RECONCILIATION.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/REPORTING-RECONCILIATION.md) |
 | Reliable Reporting production operations | docs/guides/REPORTING-OPERATIONS.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/REPORTING-OPERATIONS.md) |
-| Reliable Reporting stability policy (experimental storage subpaths) | docs/guides/REPORTING-STABILITY.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/REPORTING-STABILITY.md) |
+| Reliable Reporting stability policy (experimental storage package) | docs/guides/REPORTING-STABILITY.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/REPORTING-STABILITY.md) |
 | Validate your agent (5-command checklist) | docs/guides/VALIDATE-YOUR-AGENT.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/VALIDATE-YOUR-AGENT.md) |
 | Async patterns (polling, webhooks, deferred) | docs/guides/ASYNC-DEVELOPER-GUIDE.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/ASYNC-DEVELOPER-GUIDE.md) |
 | Async API reference | docs/guides/ASYNC-API-REFERENCE.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/ASYNC-API-REFERENCE.md) |

package/docs/migration-14.x-rc-worksheet.md

@@ -11,8 +11,8 @@ below as the publication/deployment gate.
 
 | Fact | Value |
 | --- | --- |
-| Exact npm package | `@adcp/sdk@16.0.0-beta.3` |
-| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@16.0.0-beta.3 dist.integrity` |
+| Exact npm package | `@adcp/sdk@16.0.0-beta.4` |
+| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@16.0.0-beta.4 dist.integrity` |
 | Node.js runtime | `^20.19.0 || >=22.12.0` |
 | Default AdCP wire release | `3.2.4` |
 | Maintained wire releases | `v2.5`, `v2.6`, `v3`, `3.0.0`, `3.0`, `3.0.1`, `3.0.2`, `3.0.3`, `3.0.4`, `3.0.5`, `3.0.6`, `3.0.7`, `3.0.8`, `3.0.9`, `3.0.10`, `3.0.11`, `3.0.12`, `3.0.13`, `3.0.14`, `3.0.15`, `3.0.16`, `3.0.17`, `3.0.18`, `3.0.19`, `3.0.20`, `3.0.21`, `3.0.22`, `3.0.23`, `3.0.24`, `3.0.25`, `3.1.0`, `3.1`, `3.1.1`, `3.1.2`, `3.1.3`, `3.1.4`, `3.1.5`, `3.1.6`, `3.1.7`, `3.1.8`, `3.1.9`, `3.1.10`, `3.1.11`, `3.1.12`, `3.1.13`, `3.1.14`, `3.1.15`, `3.1.16`, `3.1.17`, `3.1.18`, `3.1.19`, `3.1.20`, `3.1.21`, `3.1.22`, `3.1.23`, `3.1.24`, `3.2.1`, `3.2`, `3.2.2`, `3.2.3`, `3.2.4` |
@@ -21,8 +21,8 @@ below as the publication/deployment gate.
 Install exact production inputs rather than a moving range or dist-tag:
 
 ```bash
-npm install --save-exact '@adcp/sdk@16.0.0-beta.3'
-npm view '@adcp/sdk@16.0.0-beta.3' dist.integrity
+npm install --save-exact '@adcp/sdk@16.0.0-beta.4'
+npm view '@adcp/sdk@16.0.0-beta.4' dist.integrity
 ```
 
 ### Required and optional peers
@@ -32,9 +32,6 @@ Install the peer packages used by your application at versions satisfying these
 | Peer | Supported range | Installation |
 | --- | --- | --- |
 | `@a2a-js/sdk` | `^1.0.1` | Required |
-| `@aws-sdk/client-s3` | `^3.700.0` | Optional |
-| `@azure/storage-blob` | `^12.23.0` | Optional |
-| `@google-cloud/storage` | `^7.22.0 || ^8.2.0` | Optional |
 | `@modelcontextprotocol/sdk` | `^1.31.0` | Required |
 | `@opentelemetry/api` | `^1.0.0` | Optional |
 | `redis` | `^4.6.0 || ^5.0.0 || ^6.0.0` | Optional |

package/docs/migration-reporting-storage-package.md

@@ -0,0 +1,186 @@
+# Reliable Reporting storage moved to `@adcp/reporting-storage`
+
+**Applies to:** SDK 16 beta. **Kind:** breaking, by design. There are no re-export shims: the moved subpaths are gone from `@adcp/sdk`.
+
+The Reliable Reporting storage implementations now ship as their own package, `@adcp/reporting-storage`, on its own version line. `@adcp/sdk` keeps the protocol layer. If you import anything from `@adcp/sdk/reporting/gcs`, `/s3`, `/azure` or `/bigquery`, or the PostgreSQL store, row storage, managed delivery or notification activity from `@adcp/sdk/reporting/ledger`, or `createPostgresReliableReportingProductionService` from `@adcp/sdk/reporting/service`, change those imports. Nothing else changes on the wire, in the database schema, or in the ledger's behavior.
+
+Why: storage keeps its own release cadence, as Auth.js, LangGraph and OpenTelemetry do, so a storage fix does not need an SDK release and an experimental storage break does not need an SDK major. The Python SDK is making the same split (adcp-client-python#1510). See [Reliable Reporting stability policy](guides/REPORTING-STABILITY.md).
+
+## What to do
+
+1. Install the package next to the SDK. `@adcp/sdk` is a peer dependency of it, so the host keeps exactly one copy:
+
+   ```bash
+   npm install @adcp/sdk@beta @adcp/reporting-storage@beta
+   ```
+
+   Pin the storage package with `~` (`"@adcp/reporting-storage": "~0.1.0-beta.0"` while SDK 16 is in beta, `"~0.1.0"` after a stable release; a prerelease version is not matched by `~0.1.0`): it is pre-1.0 and every export is experimental. The cloud SDKs are optional peers of the new package, not of `@adcp/sdk` any more, so keep `@aws-sdk/client-s3`, `@azure/storage-blob` and `@google-cloud/storage` in your own dependencies for the providers you use.
+
+2. Change the imports using the table below, then run `tsc --noEmit`. A moved name on `@adcp/sdk/reporting/ledger` or `/service` is `TS2305: Module '"@adcp/sdk/reporting/ledger"' has no exported member 'PostgresReportingLedgerStore'`; a deleted subpath is `TS2307: Cannot find module '@adcp/sdk/reporting/gcs'`. At runtime the deleted subpaths fail with `ERR_PACKAGE_PATH_NOT_EXPORTED`, and a stale CommonJS `require` of a moved name on a kept subpath destructures to `undefined` and fails later as `X is not a constructor`, so grep JavaScript too (see [Self-grade](#self-grade)).
+
+3. If you pass `maintenance` to `createReliableReportingService`, wrap it (see [`maintenance` is now a factory](#maintenance-is-now-a-factory)).
+
+4. Re-run your own tests. No database migration is needed: every migration constant has the same SQL under its new import path.
+
+## Import mapping
+
+| Old import                                                                 | New import                                                                  |
+| -------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `@adcp/sdk/reporting/ledger`: `PostgresReportingLedgerStore`, the ledger, row-storage, object-write and change-feed migrations, `sweepExpiredReportingLedgerState`, row storage (`ReportingRowStorageV1`, bindings, providers contract, filesystem provider, conformance suite), object writes, the change feed | `@adcp/reporting-storage` |
+| `@adcp/sdk/reporting/ledger`: the managed-delivery runtime, `PostgresReportingManagedDeliveryStore`, `REPORTING_MANAGED_DELIVERY_MIGRATION`, the adapter contract and router | `@adcp/reporting-storage/managed` |
+| `@adcp/sdk/reporting/ledger`: notification activity (`createPostgresReportingNotificationActivityRuntime`, `createPostgresReportingNotificationAttemptCheckpoint`, `REPORTING_NOTIFICATION_ACTIVITY_MIGRATION`) | `@adcp/reporting-storage/notifications` |
+| `@adcp/sdk/reporting/ledger`: everything else (the `ReportingLedgerStore` interface and its types, `createReportingDeliveryHandler`, `createReportingStatusHandler`, `createSyncReportingStatusHandler`, `createReportingProducer`, health, coverage, lifecycle, row encoding and digests, `ReportingRowStoreError`) | unchanged: `@adcp/sdk/reporting/ledger` |
+| `@adcp/sdk/reporting/service`: `createPostgresReliableReportingProductionService` and its types | `@adcp/reporting-storage/service` |
+| `@adcp/sdk/reporting/service`: retention, compaction, orphan-collection and change-feed maintenance (`runReportingLedgerMaintenance`, `ReportingRetentionOptionsV1`, `ReportingCompactionOptionsV1`, `ReportingMaintenancePartialFailureError`, and the related types); `ReliableReportingMaintenanceOptionsV1` is now `ReportingLedgerMaintenanceOptionsV1` | `@adcp/reporting-storage` |
+| `@adcp/sdk/reporting/service`: `createReliableReportingService`, the conformance runner | unchanged: `@adcp/sdk/reporting/service` |
+| `@adcp/sdk/reporting/gcs` | `@adcp/reporting-storage/gcs` |
+| `@adcp/sdk/reporting/s3` | `@adcp/reporting-storage/s3` |
+| `@adcp/sdk/reporting/azure` | `@adcp/reporting-storage/azure` |
+| `@adcp/sdk/reporting/bigquery` | `@adcp/reporting-storage/bigquery` |
+| `@adcp/sdk/reporting/consumer`, `@adcp/sdk/reporting/source`, `@adcp/sdk` | unchanged |
+
+Before and after:
+
+```ts
+// Before
+import {
+  PostgresReportingLedgerStore,
+  REPORTING_LEDGER_MIGRATION,
+  createReportingProducer,
+} from '@adcp/sdk/reporting/ledger';
+import { createGcsReportingRowObjectProviderV1 } from '@adcp/sdk/reporting/gcs';
+
+// After
+import { createReportingProducer } from '@adcp/sdk/reporting/ledger';
+import { PostgresReportingLedgerStore, REPORTING_LEDGER_MIGRATION } from '@adcp/reporting-storage';
+import { createGcsReportingRowObjectProviderV1 } from '@adcp/reporting-storage/gcs';
+```
+
+### Every moved export, by new subpath
+
+<details>
+<summary>84 exports of <code>@adcp/reporting-storage</code></summary>
+
+`FilesystemReportingRowObjectProviderOptionsV1`, `PostgresReportingLedgerStore`, `PostgresReportingLedgerStoreOptions`, `REPORTING_LEDGER_CHANGES_MIGRATION`, `REPORTING_LEDGER_FINALITY_FENCE_CONSTRAINT`, `REPORTING_LEDGER_FINALITY_WRITER_FENCE_MIGRATION`, `REPORTING_LEDGER_MIGRATION`, `REPORTING_OBJECT_WRITE_AUTHORITY_MIGRATION`, `REPORTING_OBJECT_WRITE_MIGRATION`, `REPORTING_ROW_DEFAULT_KEY_TEMPLATE`, `REPORTING_ROW_KEY_PLACEHOLDERS`, `REPORTING_ROW_NATIVE_VERSION_REF_MAX_LENGTH`, `REPORTING_ROW_OBJECT_REF_MAX_LENGTH`, `REPORTING_ROW_STORAGE_MIGRATION`, `REPORTING_ROW_STORAGE_TABLES`, `ReportingChangeCursorExpiredError`, `ReportingChangeFeedMaintenanceOptionsV1`, `ReportingChangeKindV1`, `ReportingChangeRecordV1`, `ReportingChangesPageV1`, `ReportingCompactionOptionsV1`, `ReportingLedgerMaintenanceOptionsV1`, `ReportingLedgerMaintenanceStoreV1`, `ReportingLedgerMaintenanceTaskNameV1`, `ReportingLedgerMaintenanceTaskResultV1`, `ReportingMaintenancePartialFailureError`, `ReportingObjectRowBindingV1`, `ReportingObjectWriteAuthorityStoreV1`, `ReportingObjectWriteBindingV1`, `ReportingObjectWriteConflictError`, `ReportingObjectWriteContextV1`, `ReportingObjectWriteCursorV1`, `ReportingObjectWriteNotRevokedError`, `ReportingObjectWritePlanV1`, `ReportingObjectWriteScopeV1`, `ReportingObjectWriteStoreV1`, `ReportingObjectWriteV1`, `ReportingOrphanBindingResultV1`, `ReportingOrphanCollectionOptionsV1`, `ReportingOrphanCollectionResultV1`, `ReportingOrphanCollectionStateV1`, `ReportingPgPool`, `ReportingPostgresRowBindingV1`, `ReportingPreparedRowSetV1`, `ReportingRetentionOptionsV1`, `ReportingRowBindingDefinitionV1`, `ReportingRowBindingSelectionInputV1`, `ReportingRowChunkLocatorV1`, `ReportingRowObjectContextV1`, `ReportingRowObjectDeleteInputV1`, `ReportingRowObjectGetInputV1`, `ReportingRowObjectListEntryV1`, `ReportingRowObjectListInputV1`, `ReportingRowObjectLocationV1`, `ReportingRowObjectProviderV1`, `ReportingRowObjectPutInputV1`, `ReportingRowObjectStatInputV1`, `ReportingRowSetHandleV1`, `ReportingRowSetPrepareInputV1`, `ReportingRowStorageOptionsV1`, `ReportingRowStorageV1`, `RunReportingLedgerMaintenanceInputV1`, `assertReportingLedgerMaintenanceOptions`, `assertReportingObjectWriteScope`, `assertReportingRowKeyTemplateV1`, `assertReportingRowPrefixV1`, `createFilesystemReportingRowObjectProviderV1`, `decodeReportingChangeCursorV1`, `encodeReportingChangeCursorV1`, `isLegacyAccountChangeCursor`, `isReportingObjectWriteConflictError`, `isReportingObjectWriteNotRevokedError`, `probeReportingRowStorageSchemaV1`, `renderReportingRowObjectKeyV1`, `reportingLedgerMaintenance`, `reportingObjectWriteName`, `reportingObjectWritePlanFingerprint`, `reportingObjectWriteScopeKey`, `reportingRowAccountKeyV1`, `reportingRowRevisionKeyV1`, `reportingRowWriteIntentIdV1`, `runReportingLedgerMaintenance`, `runReportingRowObjectProviderConformanceV1`, `sweepExpiredReportingLedgerState`
+
+</details>
+
+<details>
+<summary>35 exports of <code>@adcp/reporting-storage/managed</code></summary>
+
+`CreateReportingManagedDeliveryAdapterRouterOptionsV1`, `CreateReportingManagedDeliveryRuntimeOptionsV1`, `PostgresReportingManagedDeliveryStore`, `PostgresReportingManagedDeliveryStoreOptions`, `REPORTING_ADAPTER_PROBE_DEADLINE_MILLISECONDS_V1`, `REPORTING_DESTINATION_PATTERNS_V1`, `REPORTING_DESTINATION_TRANSPORT_PATTERN_V1`, `REPORTING_MANAGED_DELIVERY_MIGRATION`, `ReportingDestinationAuthorizationV1`, `ReportingDestinationPatternV1`, `ReportingDestinationRevocationLeaseV1`, `ReportingManagedDeliveryAdapterRouterV1`, `ReportingManagedDeliveryAdapterV1`, `ReportingManagedDeliveryAdvertisedPoliciesV1`, `ReportingManagedDeliveryLeaseV1`, `ReportingManagedDeliveryProbeErrorV1`, `ReportingManagedDeliveryRouteCountsV1`, `ReportingManagedDeliveryRouteDescriptionV1`, `ReportingManagedDeliveryRouteV1`, `ReportingManagedDeliveryRoutingErrorCodeV1`, `ReportingManagedDeliveryRoutingErrorV1`, `ReportingManagedDeliveryRoutingOperationV1`, `ReportingManagedDeliveryRuntimeV1`, `ReportingManagedDeliveryStore`, `ReportingManagedDeliveryWorkerOptionsV1`, `ReportingManagedDeliveryWorkerResultV1`, `UNROUTED_REPORTING_ROUTE_KEY_V1`, `adjustmentReceiptEvidenceMatches`, `assertCredentialFreeReportingResourceLocationV1`, `assertMaterializationOutcome`, `createReportingManagedDeliveryAdapterRouterV1`, `createReportingManagedDeliveryRuntime`, `readManagedReportingResource`, `receiptEvidenceMatches`, `runManagedDeliveryWorker`
+
+</details>
+
+<details>
+<summary>20 exports of <code>@adcp/reporting-storage/notifications</code></summary>
+
+`PostgresReportingNotificationActivityOptions`, `PostgresReportingNotificationActivityRuntime`, `REPORTING_NOTIFICATION_ACTIVITY_MIGRATION`, `ReportingAccountActivityPageV1`, `ReportingAccountActivityRecordV1`, `ReportingAccountActivityV1`, `ReportingDeliveryReadyActivityV1`, `ReportingLedgerChangedActivityV1`, `ReportingLifecycleActivityV1`, `ReportingNotificationActivityPageV1`, `ReportingNotificationActivityRecordV1`, `ReportingNotificationActivityV1`, `ReportingNotificationAttemptCheckpointV1`, `ReportingNotificationProjectionErrorV1`, `ReportingNotificationRecoveryMetricsV1`, `ReportingNotificationRetryableSuppressionError`, `createPostgresReportingNotificationActivityRuntime`, `createPostgresReportingNotificationAttemptCheckpoint`, `getReportingNotificationActivityMigration`, `recipientTableName`
+
+</details>
+
+<details>
+<summary>3 exports of <code>@adcp/reporting-storage/service</code></summary>
+
+`CreatePostgresReliableReportingProductionServiceOptionsV1`, `PostgresReliableReportingProductionServiceV1`, `createPostgresReliableReportingProductionService`
+
+</details>
+
+<details>
+<summary>13 exports of <code>@adcp/reporting-storage/gcs</code></summary>
+
+`CreateGcsReportingManagedDeliveryAdapterOptionsV1`, `CreateGcsReportingRowObjectProviderOptionsV1`, `GcsReportingObjectFenceV1`, `GcsReportingReadAuthorizationV1`, `GcsReportingReadScopeV1`, `GcsReportingReaderOptionsV1`, `ReportingGcsFenceError`, `createGcsReportingManagedDeliveryAdapterV1`, `createGcsReportingObjectFenceV1`, `createGcsReportingReferenceResolverV1`, `createGcsReportingResourceReaderV1`, `createGcsReportingRowObjectProviderV1`, `isReportingGcsFenceError`
+
+</details>
+
+<details>
+<summary>2 exports of <code>@adcp/reporting-storage/s3</code></summary>
+
+`CreateS3ReportingRowObjectProviderOptionsV1`, `createS3ReportingRowObjectProviderV1`
+
+</details>
+
+<details>
+<summary>2 exports of <code>@adcp/reporting-storage/azure</code></summary>
+
+`CreateAzureBlobReportingRowObjectProviderOptionsV1`, `createAzureBlobReportingRowObjectProviderV1`
+
+</details>
+
+<details>
+<summary>10 exports of <code>@adcp/reporting-storage/bigquery</code></summary>
+
+`BigQueryReportingWarehouseSinkV1`, `CreateBigQueryReportingWarehouseSinkOptionsV1`, `REPORTING_WAREHOUSE_SINK_MIGRATION`, `ReportingBigQueryClientV1`, `ReportingWarehouseRowContextV1`, `createBigQueryReportingWarehouseSinkV1`, `reportingWarehouseCurrentRowsViewSqlV1`, `reportingWarehouseDefaultTablesSqlV1`, `reportingWarehouseJobIdV1`, `reportingWarehouseLoadDeadlineV1`
+
+</details>
+
+## Behavior changes
+
+### `maintenance` is now a factory
+
+The SDK does not know what maintenance a store needs, and retention, compaction and orphan collection are about the PostgreSQL store's data model. So `createReliableReportingService({ maintenance })` takes a factory, and `@adcp/reporting-storage` supplies the PostgreSQL one:
+
+```ts
+// Before
+createReliableReportingService({
+  store,
+  maintenance: { retention: { enabled: true }, changeFeed: true },
+});
+
+// After
+import { reportingLedgerMaintenance } from '@adcp/reporting-storage';
+
+createReliableReportingService({
+  store,
+  maintenance: reportingLedgerMaintenance({ retention: { enabled: true }, changeFeed: true }),
+});
+```
+
+Passing the old options object now fails at construction with `maintenance must be a factory, not an options object` (and in TypeScript as `Type '{ retention: ... }' provides no match for the signature '(context: ReliableReportingMaintenanceContextV1): ReliableReportingMaintenanceV1'`). The options are unchanged. The service still hands the factory the retention and recovery-window commitments it advertises, so retention still cannot disagree with what buyers were told, and a configuration the store cannot serve still fails when the service is constructed, not on the first scheduled pass. `service.runMaintenance()` returns the same per-task results, typed as `ReliableReportingMaintenanceTaskResultV1` (`{ task, status, result | error, partialFailure? }`). A store from another package can supply its own factory. `createPostgresReliableReportingProductionService` is unchanged: it takes `retention`, `compaction`, `changeFeed` and `orphanCollection` directly.
+
+### `service.setup.migrations` comes from the store
+
+`createReliableReportingService` no longer names the PostgreSQL migration. `service.setup.migrations` is the store's own `migrations` list (`ReportingLedgerStore.migrations`, optional). `PostgresReportingLedgerStore` lists `[REPORTING_LEDGER_MIGRATION]`. A store with nothing to install (an in-memory test double), or a decorator over the PostgreSQL store that does not forward `migrations`, gives an empty list.
+
+The type changed too: it was the tuple `readonly [typeof REPORTING_LEDGER_MIGRATION]` and is now `readonly string[]`, so `reporting.setup.migrations[0]` is `string | undefined` under `noUncheckedIndexedAccess`, and `pool.query(undefined)` fails at runtime for a store that lists nothing. Apply the list instead:
+
+```ts
+for (const sql of reporting.setup.migrations) await pool.query(sql);
+```
+
+### Error classes now live with the interface
+
+`ReportingLedgerLeaseLostError`, `ReportingLedgerPeriodRetiredError` and `ReportingLedgerContinuityError` are exported from `@adcp/sdk/reporting/ledger`, where the `ReportingLedgerStore` types are. The package re-throws these exact classes. The protocol layer still recognizes them by `name`, so a store from any package, or another copy of the SDK, is understood.
+
+### The Core service refuses managed-delivery offerings
+
+A `createReliableReportingService` without a managed-delivery composition still refuses offerings that need Managed Delivery or Reconciled Billing, now naming `@adcp/reporting-storage/service` in the error. A composition built elsewhere opts in with the exported `REPORTING_MANAGED_DELIVERY_COMPOSITION_V1` key, set to the very `store` it passes as `store`. That is an assertion by the composer, not an authentication boundary (the key is a `Symbol.for`, so any code can write it); it exists so a Core-only service cannot advertise offerings it has no runtime for by accident. Applications should not use it.
+
+### New exports on `@adcp/sdk`
+
+So a store can live outside the SDK against public API only: `compareReportingInstants`, `reportingPeriodDate`, `reportingPeriodSchedule`, `isFrozenCalendarRulesMismatch`, the receipt and verification evidence guards, `isWellFormedUnicodeString` and `getReportingDeliveryOfferingValidatorV1` (from `@adcp/sdk/reporting/ledger`); `reportingManagedDeliveryBindingV1`, `createSyncReportingReceiptsHandler`, `ReportingReceiptSyncStoreV1` and `SyncReportingReceiptsParamsV1` (from `@adcp/sdk/reporting/ledger`; the receipts handler only needs `syncReceiptBatch`); the scheduler helpers `reportingSchedulerErrorMessage`, `reportingSchedulerDelay`, `rotateReportingRoster`, `reportingDeploymentWideAccountIds`, `reportReportingSchedulerError` and `warnReportingSchedulerFailure` (from `@adcp/sdk/reporting/service`); and `DEFAULT_UNKNOWN_ERROR_RECOVERY` (from `@adcp/sdk`).
+
+## Other things that moved
+
+| Was                                                           | Now                                                                                       |
+| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `scripts/validate-reporting-gcp.mjs`                          | `packages/reporting-storage/scripts/validate-reporting-gcp.mjs` (`npm run validate:reporting-gcp` still works at the repository root) |
+| `examples/reliable-reporting-lifecycle`, `examples/reliable-reporting-service` | `packages/reporting-storage/examples/...`                                |
+| Optional peers `@aws-sdk/client-s3`, `@azure/storage-blob`, `@google-cloud/storage` on `@adcp/sdk` | optional peers of `@adcp/reporting-storage` |
+| Experimental policy for `reporting/gcs`, `s3`, `azure`, `bigquery` and the storage exports of `ledger` and `service` | the whole `@adcp/reporting-storage` package is pre-1.0 and experimental; see [REPORTING-STABILITY.md](guides/REPORTING-STABILITY.md) |
+
+The consumer-side Postgres persistence (`createPostgresReportingConsumerRuntimeV1`, `REPORTING_CONSUMER_POSTGRES_MIGRATION` under `@adcp/sdk/reporting/consumer`) and webhook activity (`createPostgresReportingWebhookActivityV1`, exported from `@adcp/sdk`) stay in the SDK for now.
+
+## Self-grade
+
+```bash
+# 1. no deleted subpath
+grep -rnE "@adcp/sdk/reporting/(gcs|s3|azure|bigquery)" src
+# 2. in every file that still imports the ledger or service subpath, no moved name (this also catches multi-line
+#    imports, `require` destructuring and JavaScript, which `tsc` does not check)
+grep -rlE "@adcp/sdk/reporting/(ledger|service)" src | xargs grep -nE "PostgresReporting|createPostgresReliable|REPORTING_[A-Z_]+_MIGRATION|createFilesystemReporting|ReportingRowStorageV1|createReportingManagedDeliveryRuntime|createPostgresReportingNotification|runReportingLedgerMaintenance|\bmaintenance:[[:space:]]*\{"
+# 3. TypeScript
+npx tsc --noEmit
+```
+
+Every line check 2 prints is either a moved name still imported from the SDK or a `maintenance:` options object to wrap.

package/examples/README.md

@@ -44,7 +44,7 @@ persists strict accepted state, produces strict readback, and refuses clears the
 provider cannot honor.
 
 Adding Reliable Reporting Core to an existing seller? Start with the
-[adapter-first installation example](./reliable-reporting-service/README.md).
+[adapter-first installation example](https://github.com/adcontextprotocol/adcp-client/blob/main/packages/reporting-storage/examples/reliable-reporting-service/README.md).
 It uses the durable ledger as the sole authority and shows trusted account,
 source-scope, timezone, and currency resolution without sample reporting data.