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

package/docs/guides/REPORTING-LEDGER.md

@@ -1,8 +1,10 @@
 # Seller Reporting Ledger
 
-`@adcp/sdk/reporting/ledger` turns a conforming reporting source into durable seller-side Reliable Reporting Core. It is separate from the buyer-side `reconcileReporting` API.
+Reliable Reporting Core turns a conforming reporting source into durable seller-side reporting. It is separate from the buyer-side `reconcileReporting` API.
 
-> **Stability:** the storage, row, change-feed, managed-delivery and warehouse-sink exports (`@adcp/sdk/reporting/gcs`, `s3`, `azure`, `bigquery`, and the `@experimental` exports of `ledger`) are experimental and may change in minor releases. Pin with `~`. See the [Reliable Reporting stability policy](REPORTING-STABILITY.md).
+Two packages make it up. `@adcp/sdk` holds the protocol layer: the `ReportingLedgerStore` interface, the protocol handlers, the producer, `createReliableReportingService` and row encoding (`@adcp/sdk/reporting/ledger`, `@adcp/sdk/reporting/service`). [`@adcp/reporting-storage`](https://github.com/adcontextprotocol/adcp-client/blob/main/packages/reporting-storage/README.md) holds the storage behind it: the PostgreSQL ledger store and migrations, row storage and its GCS, S3 and Azure providers, managed delivery, notification activity, the BigQuery sink and the production composition. Install both (`npm install @adcp/sdk@beta @adcp/reporting-storage@beta pg` while SDK 16 is in beta). Moving from the pre-split `@adcp/sdk/reporting/*` imports? See [Reliable Reporting storage moved to `@adcp/reporting-storage`](../migration-reporting-storage-package.md).
+
+> **Stability:** `@adcp/reporting-storage` is pre-1.0 and every export of it is experimental: breaking changes ship in its minor releases. Pin it with `~`. The store, transaction, lease and row-read interfaces in `@adcp/sdk/reporting/ledger` that it implements are `@experimental` too. See the [Reliable Reporting stability policy](REPORTING-STABILITY.md).
 
 ## Recommended: install the lifecycle service
 
@@ -13,7 +15,7 @@ producer, handlers, and decisioning-platform account resolver.
 
 ```ts
 import { Pool } from 'pg';
-import { PostgresReportingLedgerStore } from '@adcp/sdk/reporting/ledger';
+import { PostgresReportingLedgerStore } from '@adcp/reporting-storage';
 import { createReliableReportingService } from '@adcp/sdk/reporting/service';
 import { createAdcpServerFromPlatform } from '@adcp/sdk/server';
 
@@ -53,7 +55,7 @@ const reporting = createReliableReportingService({
   },
 });
 
-await pool.query(reporting.setup.migrations[0]);
+for (const sql of reporting.setup.migrations) await pool.query(sql);
 const installedPlatform = reporting.install(platform);
 const server = createAdcpServerFromPlatform(installedPlatform, serverOptions);
 
@@ -86,7 +88,7 @@ still use an `accountIds` roster. Production setup requires
 `activity.tenantScopeForAccount`; when an offering uses `consumer_receipt`, it
 also requires a trusted `obligatedConsumers` callback so lifecycle health can
 become reconciled only after every obligated consumer has accepted.
-See the [integrated seller example](../../examples/reliable-reporting-service/README.md#integrated-seller-production-service)
+See the [integrated seller example](https://github.com/adcontextprotocol/adcp-client/blob/main/packages/reporting-storage/examples/reliable-reporting-service/README.md#integrated-seller-production-service)
 for the full option shape.
 
 Install a buyer declaration after the account and its media-buy scope have
@@ -135,6 +137,8 @@ import {
   PostgresReportingLedgerStore,
   REPORTING_LEDGER_MIGRATION,
   sweepExpiredReportingLedgerState,
+} from '@adcp/reporting-storage';
+import {
   createReportingDeliveryHandler,
   createReportingProducer,
   createReportingStatusHandler,
@@ -162,7 +166,7 @@ const getMediaBuyDelivery = createReportingDeliveryHandler(store);
 await sweepExpiredReportingLedgerState(pool);
 ```
 
-Pass `getReportingStatus` and `getMediaBuyDelivery` directly to the matching `createAdcpServer` slots. The delivery helper serves only exact `reporting_revision_id` reads and returns the row payload bound by the ledger revision. Advertise `media_buy.reporting_delivery` in `experimental_features` together with a `media_buy.reporting_delivery` capability whose Reliable Reporting version is `1.0` only after both handlers are wired. Configure account resolution on the server: both handlers require the framework-resolved, caller-scoped account identity and never trust a request-body identity as an authorization boundary. If two callers can name the same upstream account, the resolver must issue distinct internal account IDs for their ledger namespaces. Install immutable delivery-configuration generations through `producer.installConfiguration`, call `planObligations()` after period close, and run `runWorker()` from a durable scheduler. Multiple workers are safe: PostgreSQL claims use `SKIP LOCKED`, expiring leases, and fencing generations.
+Pass `getReportingStatus` and `getMediaBuyDelivery` directly to the matching `createAdcpServer` slots. The delivery helper serves only exact `reporting_revision_id` reads and returns the row payload bound by the ledger revision. Both handlers take `pagination.max_results` as AdCP defines it, from `core/pagination-request.json`: an integer from 1 to 100, 50 when omitted. Any other value (and a `pagination` that is not an object or a `cursor` that is not a string) is refused with `VALIDATION_ERROR` (`field: 'pagination.max_results'`, `'pagination'` or `'pagination.cursor'`) before the ledger is read, so the same request behaves the same on every seller; page with `pagination.cursor`. The buyer-side walkers ask for the schema maximum, 100. Advertise `media_buy.reporting_delivery` in `experimental_features` together with a `media_buy.reporting_delivery` capability whose Reliable Reporting version is `1.0` only after both handlers are wired. Configure account resolution on the server: both handlers require the framework-resolved, caller-scoped account identity and never trust a request-body identity as an authorization boundary. If two callers can name the same upstream account, the resolver must issue distinct internal account IDs for their ledger namespaces. Install immutable delivery-configuration generations through `producer.installConfiguration`, call `planObligations()` after period close, and run `runWorker()` from a durable scheduler. Multiple workers are safe: PostgreSQL claims use `SKIP LOCKED`, expiring leases, and fencing generations.
 
 The planner supports fixed millisecond schedules and an explicit source-calendar
 day schedule. For the latter, set the existing schedule identity fields to
@@ -291,7 +295,7 @@ rows as verified canonical JSONL chunks (the shared SDK persistence layout,
 adcontextprotocol/adcp#7996):
 
 ```ts
-import { REPORTING_ROW_STORAGE_MIGRATION } from '@adcp/sdk/reporting/ledger';
+import { REPORTING_ROW_STORAGE_MIGRATION } from '@adcp/reporting-storage';
 
 await pool.query(REPORTING_ROW_STORAGE_MIGRATION); // after REPORTING_LEDGER_MIGRATION; PostgreSQL 13+
 const store = new PostgresReportingLedgerStore(pool, {
@@ -364,7 +368,7 @@ point reads or writes at a destination the host did not configure.
 import {
   PostgresReportingLedgerStore,
   createFilesystemReportingRowObjectProviderV1,
-} from '@adcp/sdk/reporting/ledger';
+} from '@adcp/reporting-storage';
 
 const store = new PostgresReportingLedgerStore(pool, {
   acknowledgeIsolatedDatabase: true,
@@ -462,6 +466,14 @@ await store.readyRowStorage();
   version at the recorded size is the same bytes) instead of downloading it
   while holding the account and object locks. A provider without `stat` falls
   back to reading the whole object there. All bundled providers implement it.
+  Also implement the optional `list({ prefix, pageToken, pageSize })`, which
+  returns `{ objects: [{ objectRef, nativeVersionRef, sizeBytes, createdAt }],
+  nextPageToken? }`: every stored version under the prefix once, in a stable
+  order (on a versioned store, noncurrent versions too, never delete markers),
+  with the version exactly as `putIfAbsent` recorded it and the time it was
+  written. The orphan collector needs it; a binding whose provider has no `list`
+  is reported as unsupported there. The conformance suite checks it (`list`) when
+  present. All bundled providers implement it.
 
 #### Cloud providers
 
@@ -472,12 +484,12 @@ reference fails `UNSAFE_BINDING`. Provider errors surface only as stable
 `ReportingRowStoreError` codes. Row buckets are separate from Managed Delivery
 buckets.
 
-**Google Cloud Storage** (`@adcp/sdk/reporting/gcs`, optional peer
+**Google Cloud Storage** (`@adcp/reporting-storage/gcs`, optional peer
 `@google-cloud/storage`):
 
 ```ts
 import { Storage } from '@google-cloud/storage';
-import { createGcsReportingRowObjectProviderV1 } from '@adcp/sdk/reporting/gcs';
+import { createGcsReportingRowObjectProviderV1 } from '@adcp/reporting-storage/gcs';
 
 const gcs = createGcsReportingRowObjectProviderV1({
   storage: new Storage(), // keyless credentials (workload identity / ADC)
@@ -500,12 +512,12 @@ const gcs = createGcsReportingRowObjectProviderV1({
 - The client needs `storage.buckets.get` for the probe plus object create, get
   and delete on the bucket.
 
-**Amazon S3 and S3-compatible stores** (`@adcp/sdk/reporting/s3`, optional peer
+**Amazon S3 and S3-compatible stores** (`@adcp/reporting-storage/s3`, optional peer
 `@aws-sdk/client-s3`):
 
 ```ts
 import { S3Client } from '@aws-sdk/client-s3';
-import { createS3ReportingRowObjectProviderV1 } from '@adcp/sdk/reporting/s3';
+import { createS3ReportingRowObjectProviderV1 } from '@adcp/reporting-storage/s3';
 
 const s3 = createS3ReportingRowObjectProviderV1({
   client: new S3Client({ region: 'us-east-1' }), // default credential chain
@@ -542,13 +554,13 @@ const s3 = createS3ReportingRowObjectProviderV1({
   `s3:GetBucketPolicyStatus` is optional. For stores without flexible
   checksums, construct the client with `requestChecksumCalculation: 'WHEN_REQUIRED'`.
 
-**Azure Blob Storage** (`@adcp/sdk/reporting/azure`, optional peer
+**Azure Blob Storage** (`@adcp/reporting-storage/azure`, optional peer
 `@azure/storage-blob`):
 
 ```ts
 import { DefaultAzureCredential } from '@azure/identity';
 import { BlobServiceClient } from '@azure/storage-blob';
-import { createAzureBlobReportingRowObjectProviderV1 } from '@adcp/sdk/reporting/azure';
+import { createAzureBlobReportingRowObjectProviderV1 } from '@adcp/reporting-storage/azure';
 
 const azure = createAzureBlobReportingRowObjectProviderV1({
   client: new BlobServiceClient('https://acmerows.blob.core.windows.net', new DefaultAzureCredential()),
@@ -677,7 +689,7 @@ an unknown ID. A revision in (a) to (d) whose content cannot be served is
 // Core-only service
 createReliableReportingService({
   // ...
-  maintenance: { compaction: { enabled: true, limit: 100 } },
+  maintenance: reportingLedgerMaintenance({ compaction: { enabled: true, limit: 100 } }),
 });
 
 // Production service
@@ -751,7 +763,8 @@ and `compactSupersededSnapshots` re-check before compacting.
 
 You do not need the production service (managed delivery, notifications and
 activity) to keep a ledger tidy. Build the store with the options you want and
-give `createReliableReportingService` a `maintenance` option. The production
+give `createReliableReportingService` a `maintenance` option built by
+`reportingLedgerMaintenance` from `@adcp/reporting-storage`. The production
 service does the same work automatically; the two share one implementation, so
 partial-failure reporting, the `maxFeedHoldDays` that retention honours, per-task
 limits and abort handling are identical.
@@ -762,7 +775,8 @@ import {
   REPORTING_LEDGER_MIGRATION,
   REPORTING_ROW_STORAGE_MIGRATION,
   REPORTING_LEDGER_CHANGES_MIGRATION,
-} from '@adcp/sdk/reporting/ledger';
+  reportingLedgerMaintenance,
+} from '@adcp/reporting-storage';
 import { createReliableReportingService } from '@adcp/sdk/reporting/service';
 
 // Apply the three migrations, then:
@@ -777,11 +791,11 @@ const reporting = createReliableReportingService({
   store,
   statusRetentionDays: 90, // the commitment advertised to buyers; retention uses it
   // ...adapters, contact, resolveSource, resolveCurrency, resolveCoverage
-  maintenance: {
+  maintenance: reportingLedgerMaintenance({
     intervalMilliseconds: 300_000, // default: at most one pass per 5 minutes
     retention: { enabled: true, recordRetentionDays: 120, limit: 100 },
     changeFeed: { changeRetentionDays: 30, maxFeedHoldDays: 7 },
-  },
+  }),
 });
 
 reporting.start({ intervalMilliseconds: 60_000, deploymentWide: true, onError });
@@ -813,12 +827,18 @@ Tasks, in order:
 | `change-feed pruning` | when `maintenance.changeFeed` is set              | `pruneChanges` with `changeRetentionDays` and `maxFeedHoldDays`.     |
 | `retention`           | when `maintenance.retention.enabled` is `true`    | `retireExpiredPeriods` with the service's `statusRetentionDays` and the feed's `maxFeedHoldDays`. |
 | `snapshot compaction` | when `maintenance.compaction.enabled` is `true`   | `compactSupersededSnapshots` with the service's `statusRetentionDays` and `automatedRecoveryWindowSeconds` (see [Compacting superseded snapshots](#compacting-superseded-snapshots-opt-in)). |
+| `orphan object collection` | when `maintenance.orphanCollection.enabled` is `true` | `collectOrphanedRowObjects`: lists each object binding under `{prefix}/{namespace_key}/` and deletes old objects nothing names. Opt-in, rate-limited and resumable; see [Orphaned object collection](REPORTING-OPERATIONS.md#adopting-row-storage-retention-and-the-change-feed). |
 
 Notes:
 
-- `maintenance` requires a `PostgresReportingLedgerStore` (or a store with the
+- The service's `maintenance` option takes a factory, not an options object:
+  the SDK does not know what maintenance a store needs, so it calls the factory
+  once at construction with the store and the retention and recovery-window
+  commitments it advertises. `reportingLedgerMaintenance(options)` is the
+  PostgreSQL one. It requires a `PostgresReportingLedgerStore` (or a store with the
   same `retireExpiredPeriods`, `pruneChanges` and `sweepRowWriteIntents`
-  methods) and fails at construction otherwise. `maintenance.changeFeed` also
+  methods, plus `collectOrphanedRowObjects` when `orphanCollection` is set) and
+  fails at construction otherwise. `maintenance.changeFeed` also
   requires `changeFeed: true` on the store, since pruning is otherwise a silent
   no-op.
 - Retention takes `statusRetentionDays` from the service, so it can never retire
@@ -838,7 +858,7 @@ In-process consumers such as pacing, alerts and warehouse loaders read from the
 ledger, never from a warehouse copy.
 
 ```ts
-import { REPORTING_LEDGER_CHANGES_MIGRATION } from '@adcp/sdk/reporting/ledger';
+import { REPORTING_LEDGER_CHANGES_MIGRATION } from '@adcp/reporting-storage';
 
 await pool.query(REPORTING_LEDGER_CHANGES_MIGRATION); // PostgreSQL 13+
 const store = new PostgresReportingLedgerStore(pool, { acknowledgeIsolatedDatabase: true, changeFeed: true });
@@ -860,30 +880,60 @@ await store.saveFeedConsumerCursor('pacing', page.cursor); // holds back pruning
   highest-numbered snapshot. An official revision is terminal, so this is always
   one index lookup.
 - `changesAfter` lists committed obligation, revision, adjustment and retirement
-  changes. Account feeds order by sequence. The deployment-wide feed (omit
-  `account_id`) orders by `(xid, seq)` and returns only changes whose
-  transaction precedes every transaction still in flight, so a slow commit is
-  never skipped. The account feed applies the same guard: a page ends before the
-  first change whose transaction has not finished (`xid` at or above the reading
-  snapshot's `xmin`), so the cursor never passes a change that commits late. The
-  page is cut there rather than filtered, because seq order and xid order can
-  differ and a filter would hand out a later change while skipping an earlier
-  one it excluded. The cost is that any older open transaction on the cluster,
-  including an idle one in another database, holds both kinds of feed back until
-  it ends; keep transactions short. An empty page therefore means either caught
-  up or held back, so poll again rather than treating it as the end of the feed.
+  changes. Every feed, account-scoped or deployment-wide (omit `account_id`),
+  orders by `(xid, seq)` and returns only changes whose transaction precedes
+  every transaction still in flight (`xid` below the reading snapshot's
+  `xmin`), so a slow commit is never skipped. The order does not depend on the
+  account lock, on the order a writer drew `seq` in, or on which lock key a
+  writer took: a change with a lower `seq` and a higher `xid` that commits late
+  is simply returned on a later page, after the cursor. The cost is that any
+  older open transaction on the cluster, including an idle one in another
+  database, holds every feed back until it ends; keep transactions short. An
+  empty page therefore means either caught up or held back, so poll again rather
+  than treating it as the end of the feed. The account scan is served by the
+  `(account_id, xid, seq)` index that `REPORTING_LEDGER_CHANGES_MIGRATION`
+  creates.
 - **A ledger database has exactly one writer SDK.** The store writes each change
-  row under the account advisory lock, taking the sequence value only after it,
-  so per-account `seq` order equals commit order. The in-flight guard above is
-  defense in depth, not a substitute: a second SDK (for example a Python
-  deployment, or a hand-written writer) that takes a different lock key, or
-  writes change rows outside the account lock, can allocate a lower `seq` that
-  commits after a higher one. The guard narrows that window but cannot close it
-  for every interleaving, so run one writer SDK per ledger database and give
-  another SDK its own database. `pruneChanges` only deletes changes older than
-  `changeRetentionDays`, far longer than any transaction should stay open, and
-  consumer holds compare against cursors the feed itself returned, so neither
-  adds a new ordering assumption.
+  row under the account advisory lock. The feed no longer needs that lock for
+  its order, but a second SDK is still unsupported: it can write rows the first
+  SDK's lifecycle, retention and idempotency logic does not know about. Give
+  another SDK (for example a Python deployment) its own database. `pruneChanges`
+  only deletes changes older than `changeRetentionDays`, far longer than any
+  transaction should stay open, and consumer holds compare against cursors the
+  feed itself returned, so neither adds an ordering assumption.
+- **Upgrading from account cursors that carry only `seq`.** Account feeds used
+  to order by `seq` and cut each page before the first in-flight change. An old
+  account cursor is `{ seq }` with no `xid`. `changesAfter` accepts it and maps
+  it to the position `(xid, seq)` where `xid` is the smaller of the oldest `xid`
+  among the account's changes after that `seq` and the reading snapshot's `xmin`.
+  Every change after the old `seq` has an `xid` at or above both (a change that
+  has not committed yet belongs to a transaction at or above `xmin`), so nothing
+  is skipped. The cost is that changes the consumer already read can be returned
+  again: those with a lower `seq` and a higher `xid`, and, when a long
+  transaction was open at that moment, every change committed since it began.
+  Treat redelivery as normal, as for any at-least-once consumer. The returned cursor is in the new
+  format, even on an empty page. A legacy cursor fails with `CURSOR_EXPIRED` if
+  any change with a higher `seq` was pruned (`adcp_reporting_change_account_horizon.pruned_through_seq`
+  still records the highest pruned `seq` for this check). A consumer row saved
+  before the upgrade has a NULL `cursor_xid` and holds retention by `seq` until
+  the consumer saves its next cursor; `saveFeedConsumerCursor` given a legacy
+  cursor maps it the same way. Re-apply `REPORTING_LEDGER_CHANGES_MIGRATION`
+  before starting the new binary: it adds the account horizon's `xid` columns,
+  replaces the consumer table's check constraint, and creates the new index. On
+  a large changes table, create the index first with `CREATE INDEX CONCURRENTLY
+  IF NOT EXISTS adcp_reporting_changes_account_xid ON adcp_reporting_changes
+  (account_id, xid, seq)`, because a plain `CREATE INDEX` blocks appends while it
+  builds; the migration then skips it. The older
+  `adcp_reporting_changes_account (account_id, seq)` index is left in place and
+  serves the legacy-cursor mapping; drop it once no legacy cursor remains.
+- **Do not run the old and new SDK's change-feed maintenance together.** An older
+  host's `pruneChanges`, `retireExpiredPeriods` and compaction hold an account
+  consumer's changes by `seq` alone and record only `pruned_through_seq`, so
+  against a consumer that holds new-format cursors they can prune a change the
+  consumer has not read and never advance the horizon the new reader checks.
+  Stop the older hosts' maintenance (or the hosts) before the new binary reads
+  the feed. Rolling back is not supported once a consumer has saved a new-format
+  account cursor: the older SDK rejects it, so reset those consumers.
 - `pruneChanges` deletes changes older than `changeRetentionDays` (default 30)
   that every consumer updated within `maxFeedHoldDays` (default 7) has passed.
   An older cursor throws `ReportingChangeCursorExpiredError`; resynchronize from
@@ -918,7 +968,7 @@ await store.saveFeedConsumerCursor('pacing', page.cursor); // holds back pruning
 
 ### BigQuery warehouse sink
 
-`@adcp/sdk/reporting/bigquery` loads committed revisions into your own BigQuery
+`@adcp/reporting-storage/bigquery` loads committed revisions into your own BigQuery
 tables for analysts. The warehouse copy is derived and non-authoritative. It
 is never read for serving or verification, so its table names, columns,
 partitioning and retention are yours.
@@ -928,7 +978,7 @@ import { BigQuery } from '@google-cloud/bigquery';
 import {
   REPORTING_WAREHOUSE_SINK_MIGRATION,
   createBigQueryReportingWarehouseSinkV1,
-} from '@adcp/sdk/reporting/bigquery';
+} from '@adcp/reporting-storage/bigquery';
 
 await pool.query(REPORTING_WAREHOUSE_SINK_MIGRATION); // after REPORTING_LEDGER_CHANGES_MIGRATION
 const bigquery = new BigQuery({ projectId: 'analytics-prod' }); // ADC / workload identity
@@ -1109,9 +1159,13 @@ Core remains the default and has no destination, external-resource, or receipt d
 ```ts
 import {
   PostgresReportingLedgerStore,
+} from '@adcp/reporting-storage';
+import {
   PostgresReportingManagedDeliveryStore,
   REPORTING_MANAGED_DELIVERY_MIGRATION,
   createReportingManagedDeliveryRuntime,
+} from '@adcp/reporting-storage/managed';
+import {
   reportingManagedDeliveryBindingV1,
 } from '@adcp/sdk/reporting/ledger';
 
@@ -1182,7 +1236,7 @@ A seller often delivers one feed through several transports: one buyer takes fil
 import {
   createReportingManagedDeliveryAdapterRouterV1,
   createReportingManagedDeliveryRuntime,
-} from '@adcp/sdk/reporting/ledger';
+} from '@adcp/reporting-storage/managed';
 
 const adapter = createReportingManagedDeliveryAdapterRouterV1({
   routes: [
@@ -1262,12 +1316,14 @@ only for health changes:
 ```ts
 import { createPostgresPersistentNotificationRuntime } from '@adcp/sdk/server';
 import {
-  createPostgresReportingNotificationActivityRuntime,
-  createPostgresReportingNotificationAttemptCheckpoint,
   PostgresReportingLedgerStore,
   REPORTING_LEDGER_FINALITY_WRITER_FENCE_MIGRATION,
   REPORTING_LEDGER_MIGRATION,
-} from '@adcp/sdk/reporting/ledger';
+} from '@adcp/reporting-storage';
+import {
+  createPostgresReportingNotificationActivityRuntime,
+  createPostgresReportingNotificationAttemptCheckpoint,
+} from '@adcp/reporting-storage/notifications';
 
 // Build the durable pre-POST checkpoint first. The notification runtime needs
 // it, and the activity runtime verifies it targets the same durable store —

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).