@adcp/sdk 15.4.0 → 15.6.0

package/docs/guides/REPORTING-LEDGER.md

@@ -272,6 +272,380 @@ Official configurations also pin a `finalityPolicy` (`policyId` plus `source_fin
 
 Every revision stores its rows together with an RFC 8785 JCS SHA-256 binding and exact decimal control totals for requested numeric metrics. A revision number and obligation are immutable. Official revisions are terminal; later source corrections are immutable adjustments bound to the official revision, never superseding revisions. Status snapshots omit row payloads, are capped at 8 MiB, expire after 15 minutes, and keep cursor pages stable over the flat obligation/revision/adjustment union. A periods response returns an opaque `changes_checkpoint`; echo that value verbatim as `changes_after` rather than supplying a timestamp. Account-scoped write/snapshot locks make those checkpoints gap-free for SDK store writes. The default table set is deployment-wide; use a dedicated database/schema and acknowledge that boundary explicitly. `sourceScope` must contain opaque routing identities only—never credentials or bearer tokens—because it is retained with the obligation. Retained resource locations are held to the same rule, and at the seam that persists them rather than only in the worker's pre-flight, because a caller driving `settleMaterialization` directly would otherwise store a presigned location that `get_reporting_status` then publishes. Query and fragment are refused on the raw string rather than on a successful parse, because a relative path carrying a presigning query never parsed as a URL at all; userinfo is refused as a colon-separated pair before the `@`, which is the credential shape, plus any `http(s)` userinfo at all. A blanket `@` rule would refuse `abfss://container@account.dfs.core.windows.net/...` and a Snowflake stage reference, neither of which carries a secret.
 
+## Row storage
+
+By default every revision document carries its rows inline. At pulse cadence
+that keeps bulk report bytes in the transactional database. Opt in to row
+storage to keep only the revision header in the ledger document and store
+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';
+
+await pool.query(REPORTING_ROW_STORAGE_MIGRATION); // after REPORTING_LEDGER_MIGRATION; PostgreSQL 13+
+const store = new PostgresReportingLedgerStore(pool, {
+  acknowledgeIsolatedDatabase: true,
+  rowStorage: true,
+});
+await store.readyRowStorage();
+```
+
+`createPostgresReliableReportingProductionService` accepts the same
+`rowStorage` option and adds the migration to `setup.migrations`.
+
+- Rows are split into 500-row segments and chunks of at most 10,000 rows or
+  8 MiB. Chunk, segment and manifest digests are committed with the revision,
+  and every read is verified before rows are released. Delivery pages read only
+  the segments they need.
+- A revision whose rows are byte-identical to a live row set in the same
+  obligation is stored as a header-only revision. It gets a new identity,
+  freshness and binding, and references the existing chunks
+  (`rows_shared_from_row_set_id`), so an unchanged pulse uploads nothing.
+- Revisions written before you enable row storage keep their inline rows.
+  Reads handle both forms whether or not the option is set.
+- Missing or corrupt rows inside the retention window make
+  `get_media_buy_delivery` fail with `SERVICE_UNAVAILABLE` rather than reporting
+  the revision as absent; expired rows read like an unknown revision.
+- Managed Delivery claims hydrate PostgreSQL-stored rows automatically.
+
+To move existing inline rows into row storage, run the resumable migration in
+bounded batches. A revision whose rows do not reproduce its committed binding is
+reported in `quarantined` and left untouched:
+
+```ts
+let cursor: string | undefined;
+do {
+  const batch = await store.migrateInlineRows({ limit: 100, cursor });
+  if (batch.quarantined.length) console.warn('unverifiable inline rows', batch.quarantined);
+  cursor = batch.cursor;
+} while (cursor);
+```
+
+Removing rows from ledger documents frees space only after `VACUUM FULL` or an
+online repack of `adcp_reporting_revisions` and `adcp_reporting_adjustments`.
+
+### Object storage bindings
+
+Rows can live in object storage instead of PostgreSQL. A binding is defined in
+host code, which makes the configuration the allowlist: the database records
+which binding each revision used and its identity digest, but it can never
+point reads or writes at a destination the host did not configure.
+
+```ts
+import {
+  PostgresReportingLedgerStore,
+  createFilesystemReportingRowObjectProviderV1,
+} from '@adcp/sdk/reporting/ledger';
+
+const store = new PostgresReportingLedgerStore(pool, {
+  acknowledgeIsolatedDatabase: true,
+  rowStorage: {
+    deploymentNamespace: 'prod-us',
+    bindings: {
+      inline: { kind: 'postgres' },
+      reports: {
+        kind: 'object',
+        provider: 'filesystem', // or a cloud provider registered below
+        location: { root: 'reports' },
+        prefix: 'adcp-rows',
+        compression: 'gzip',
+      },
+    },
+    providers: {
+      filesystem: createFilesystemReportingRowObjectProviderV1({ roots: { reports: '/var/lib/adcp/rows' } }),
+    },
+    selectRowBinding: ({ canonical_byte_count }) => (canonical_byte_count < 256 * 1024 ? 'inline' : 'reports'),
+  },
+});
+await store.readyRowStorage();
+```
+
+- Each chunk is one object, written create-only. If an object already exists at
+  a planned key, it is adopted only when its bytes decode to the exact chunk;
+  otherwise the commit fails with `CONTENT_CONFLICT`.
+- Keys always start with `{prefix}/{namespace_key}/` and use a hashed account
+  segment, never a raw account ID. Override `keyTemplate` with the placeholders
+  in `REPORTING_ROW_KEY_PLACEHOLDERS`; templates must include
+  `{content_sha256}` and `{chunk_index}`.
+- An upload runs only while the obligation lease still covers
+  `writeDeadlineMilliseconds` plus five seconds. A fenced write intent records
+  every object the upload created, and the ledger commit closes the intent in
+  the same transaction. Objects of an upload that never committed are left for
+  the intent sweep.
+- Every read verifies the stored bytes against the recorded physical digest
+  before decompressing, then verifies segments, chunks and the revision binding.
+- Keep a retired binding configured while revisions still reference it.
+- The filesystem provider identifies each write by inode, birth time, mtime
+  and size, stamping a random sub-millisecond mtime on every write. It needs a
+  filesystem with sub-second mtime and, ideally, birth time (ext4, XFS, APFS,
+  NTFS). On a coarse filesystem (FAT, some NFS mounts, ext3), a reused inode
+  re-created with identical bytes in the same second gets the same version,
+  so a delayed delete could remove the replacement. The conformance check
+  `write-unique-version` fails on such filesystems. That failure means the
+  filesystem is wrong, not the code.
+- Custom providers implement `ReportingRowObjectProviderV1`. Run
+  `runReportingRowObjectProviderConformanceV1(provider, { location, prefix })`
+  against a dedicated test prefix before using one.
+
+#### Cloud providers
+
+Cloud providers wrap official clients that the host constructs with its own
+credentials. A binding's `location` holds only non-secret coordinates, and its
+optional `credentialRef` names one of the clients you injected; an unknown
+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`):
+
+```ts
+import { Storage } from '@google-cloud/storage';
+import { createGcsReportingRowObjectProviderV1 } from '@adcp/sdk/reporting/gcs';
+
+const gcs = createGcsReportingRowObjectProviderV1({
+  storage: new Storage(), // keyless credentials (workload identity / ADC)
+  clients: { 'tenant-eu': euStorage }, // optional, selected by credentialRef
+});
+// binding: { kind: 'object', provider: 'gcs', location: { bucket: 'acme-adcp-rows' }, prefix: 'adcp-rows' }
+// providers: { gcs }
+```
+
+- Writes are single-request uploads with `ifGenerationMatch: 0` and a declared
+  MD5, without `Content-Encoding`. The recorded native version is the object
+  generation; reads and deletes pin it, and reads never transcode.
+- The probe requires uniform bucket-level access and enforced public access
+  prevention. Versioning, soft delete and retention policies are allowed. A
+  lifecycle `Delete` rule that can match live objects under the binding prefix
+  (no `matchesPrefix`, or a prefix that overlaps it) is refused; rules limited
+  to noncurrent versions (`isLive: false`, `numNewerVersions`,
+  `daysSinceNoncurrentTime`, `noncurrentTimeBefore`) are allowed. Keep
+  retention-driven deletion in the ledger's pruning, not in bucket lifecycle.
+- 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
+`@aws-sdk/client-s3`):
+
+```ts
+import { S3Client } from '@aws-sdk/client-s3';
+import { createS3ReportingRowObjectProviderV1 } from '@adcp/sdk/reporting/s3';
+
+const s3 = createS3ReportingRowObjectProviderV1({
+  client: new S3Client({ region: 'us-east-1' }), // default credential chain
+});
+// binding: { kind: 'object', provider: 's3', location: { bucket: 'acme-adcp-rows', region: 'us-east-1' }, prefix: 'adcp-rows' }
+// providers: { s3 }
+```
+
+- Endpoint, region, credentials and path style come only from the client you
+  inject; `location` accepts just `bucket` and an optional `region`, which the
+  probe checks against the client.
+- **Bucket versioning is required.** Writes use `PutObject` with
+  `If-None-Match: *` (a 409 is retried once). The recorded native version is
+  the write-unique `VersionId`; reads pin it with `VersionId`, and deletes
+  confirm the exact version with `HeadObject`, then delete by `VersionId`.
+  Deletes must be fenced to one write, and an ETag identifies content, not a
+  write: a delayed delete (for example an intent sweep removing an abandoned
+  upload) pinned to an ETag would also remove a replacement object later
+  re-created with identical bytes at the same key. The probe therefore refuses
+  any bucket whose `GetBucketVersioning` status is not `Enabled` (suspended or
+  unversioned), and `putIfAbsent` refuses a result with no `VersionId`.
+  Deleting a specific `VersionId` permanently removes that version without
+  leaving a delete marker, so retention still frees storage; noncurrent-version
+  lifecycle rules are not needed for rows this provider deletes.
+- S3-compatible stores may ignore `If-None-Match`, so the probe writes a probe
+  key under the binding prefix twice and requires the second write to fail with
+  412, then deletes it. It also refuses missing or inaccessible buckets, a
+  bucket policy reported as public, and enabled lifecycle `Expiration` rules
+  that can match the prefix. The probe cannot verify Block Public Access on
+  every store, so keep row buckets private.
+- The client needs `s3:ListBucket` (HeadBucket),
+  `s3:GetLifecycleConfiguration`, `s3:GetBucketVersioning`, object put/get,
+  `s3:GetObjectVersion` and `s3:DeleteObjectVersion`.
+  `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/storage-blob`):
+
+```ts
+import { DefaultAzureCredential } from '@azure/identity';
+import { BlobServiceClient } from '@azure/storage-blob';
+import { createAzureBlobReportingRowObjectProviderV1 } from '@adcp/sdk/reporting/azure';
+
+const azure = createAzureBlobReportingRowObjectProviderV1({
+  client: new BlobServiceClient('https://acmerows.blob.core.windows.net', new DefaultAzureCredential()),
+});
+// binding: { kind: 'object', provider: 'azure_blob', location: { account: 'acmerows', container: 'adcp-rows' }, prefix: 'adcp-rows' }
+// providers: { azure_blob: azure }
+```
+
+- `location` names the storage `account` and `container`; the selected client
+  must belong to that account. The endpoint and credentials come only from
+  the client.
+- **Blob versioning is required** on the storage account. Writes are
+  block-blob uploads with `If-None-Match: *`. A 409 `BlobAlreadyExists` or 412
+  adopts the existing blob. The recorded native version is the write-unique
+  `versionId`; reads and deletes pin it, and only count a response that echoes
+  that exact version. ETags are content-derived, so they cannot fence a delayed
+  delete away from an identical re-upload at the same key. The probe's
+  create-only write must return a `versionId` (otherwise `UNSAFE_BINDING`), and
+  `putIfAbsent` refuses a result without one. Deleting a specific version
+  permanently removes it, so retention still frees storage. Azurite does not
+  implement blob versioning and cannot back this provider. Metadata names are
+  stored as C# identifiers (`adcp_intent`).
+- The probe refuses missing or inaccessible containers and containers with
+  anonymous access. Like S3, it proves create-only writes empirically with a
+  probe blob under the prefix. Lifecycle management policies are account-level
+  and are not visible to the data-plane client, so make sure none can delete
+  blobs under the binding prefix.
+- The client needs read, write and delete on blobs in the container (for
+  example `Storage Blob Data Contributor`), plus permission to delete
+  versions.
+
+### Retention
+
+Retention is period-aligned and opt-in. A period becomes eligible once both its
+end and its latest publication are older than `max(statusRetentionDays,
+recordRetentionDays)`, no worker holds its lease, and no Managed Delivery
+materialization still references it. Superseded snapshots stay readable for the
+whole window, as the protocol requires.
+
+When the change feed is installed, retention also waits for registered feed
+consumers. A period is held while any live consumer (one whose cursor was saved
+within `maxFeedHoldDays`, default 7) has not yet passed that period's change
+rows, in the consumer's own feed order. This is the same rule `pruneChanges`
+uses, so a warehouse sink that is briefly down does not lose revisions it has
+not loaded. A held period is simply not retired on this pass. A consumer silent
+for longer than `maxFeedHoldDays` stops holding, so a dead consumer cannot block
+retention forever; it has then fallen behind retention (see the warehouse sink
+below). Pass `maxFeedHoldDays` to `retireExpiredPeriods`; the production service
+passes `changeFeed.maxFeedHoldDays` for you so retention and feed pruning agree.
+
+```ts
+await store.retireExpiredPeriods({ statusRetentionDays: 30, recordRetentionDays: 45, limit: 100 });
+await store.sweepRowWriteIntents({ limit: 100 }); // abandoned object uploads
+```
+
+Retirement runs in three resumable phases. First it records a `retiring`
+tombstone and marks the period's rows as expired. Then it deletes external row
+objects at their recorded versions. Finally it deletes the period's rows and
+ledger records together. The tombstone keeps the final revision ID and digest,
+and planners never re-create a retired period. `ledger_retained_from` advances
+because the retired obligations no longer exist.
+
+`createPostgresReliableReportingProductionService` accepts
+`retention: { enabled: true, recordRetentionDays?, limit? }`. Its scheduler
+always sweeps abandoned row uploads and expired cursor snapshots and
+checkpoints, and retires periods when retention is enabled.
+
+### Host reads: current revisions and the change feed
+
+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';
+
+await pool.query(REPORTING_LEDGER_CHANGES_MIGRATION); // PostgreSQL 13+
+const store = new PostgresReportingLedgerStore(pool, { acknowledgeIsolatedDatabase: true, changeFeed: true });
+
+const current = await store.getCurrentRevision({ account_id, reporting_obligation_id });
+const { revisions, cursor: next } = await store.listCurrentRevisions({
+  account_id,
+  period_start_from: '2026-10-01T00:00:00Z',
+  period_start_to: '2026-10-08T00:00:00Z',
+});
+
+let cursor = await loadCursor();
+const page = await store.changesAfter({ account_id, cursor, kinds: ['revision'] });
+// ...apply page.records...
+await store.saveFeedConsumerCursor('pacing', page.cursor); // holds back pruning
+```
+
+- The current revision is the official revision if one exists, otherwise the
+  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.
+- `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
+  `listCurrentRevisions`.
+- Period retention honours the same hold: `retireExpiredPeriods` does not retire
+  a period while a live consumer has not read its changes. A consumer that
+  stays silent past `maxFeedHoldDays` stops holding, and its unread changes can
+  then point at revisions whose period was retired.
+- The production service accepts `changeFeed: true | { changeRetentionDays,
+  maxFeedHoldDays }` and prunes the feed on its scheduler.
+
+### BigQuery warehouse sink
+
+`@adcp/sdk/reporting/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.
+
+```ts
+import { BigQuery } from '@google-cloud/bigquery';
+import {
+  REPORTING_WAREHOUSE_SINK_MIGRATION,
+  createBigQueryReportingWarehouseSinkV1,
+} from '@adcp/sdk/reporting/bigquery';
+
+await pool.query(REPORTING_WAREHOUSE_SINK_MIGRATION); // after REPORTING_LEDGER_CHANGES_MIGRATION
+const sink = createBigQueryReportingWarehouseSinkV1({
+  store, // PostgresReportingLedgerStore with changeFeed: true
+  db: pool,
+  bigquery: new BigQuery({ projectId: 'analytics-prod' }), // ADC / workload identity
+  name: 'warehouse',
+  projectId: 'analytics-prod',
+  datasetId: 'reporting',
+  rowsTableId: 'media_buy_delivery_rows',
+  revisionsTableId: 'media_buy_delivery_revisions',
+  location: 'US',
+  mapRow: row => ({ media_buy_id: row.media_buy_id, impressions: row.impressions, spend: row.spend }),
+  labels: { component: 'adcp-reporting' },
+});
+await bigquery.query({ query: sink.defaultTablesSql }); // or create your own tables
+await bigquery.query({ query: sink.currentRowsViewSql });
+setInterval(() => void sink.runOnce(), 15 * 60_000);
+```
+
+- Each run follows the change feed and reads every revision's rows through the
+  store's verified reader. It loads rows first and revision metadata second,
+  in one load job per table per tick. The sink always adds
+  `reporting_revision_id`, `reporting_obligation_id`, `account_id`,
+  `revision_number`, `finality`, `period_date` (the period's date in its source
+  timezone) and `ordinal` to your mapped columns.
+- Batches are planned durably before loading, and job IDs derive from the
+  change-feed range. A crash between a load and the cursor commit replays the
+  same batch under the same job ID, which BigQuery refuses to run twice. A job
+  that finished with an error is retried under a new attempt for that table
+  only.
+- Query `current_rows`, not the raw rows table. Pacing snapshots are
+  cumulative, so summing across revisions double-counts. The view keeps each
+  obligation's current revision.
+- The sink registers as a change-feed consumer, so `pruneChanges` keeps changes
+  it has not loaded yet, and `retireExpiredPeriods` keeps the periods it has not
+  loaded yet, in both cases only while its cursor was saved within
+  `maxFeedHoldDays`. Superseded snapshots are the intraday pacing curve, and the
+  warehouse may keep them as long as you like.
+- `runOnce()` resolves with `{ idle, revisions, rows, missing }`. `missing`
+  lists revision IDs the feed announced that were retired before the batch ran.
+  A non-empty `missing` means the sink fell behind retention (it was down longer
+  than `maxFeedHoldDays` plus the retention window): the warehouse lacks those
+  revisions. Backfill them from another source or accept the gap. The cursor
+  still advances so the sink is not stuck. After a crash and replay of a planned
+  batch, a listed revision may already have been loaded by the first attempt.
+- The sink uses only `dataset().table().load()`, `job().getMetadata()` and
+  `query()` from the official client you construct. It adds no dependency.
+
 ## Managed Delivery and Reconciled Billing
 
 Core remains the default and has no destination, external-resource, or receipt dependency. To opt into the higher tiers, apply `REPORTING_MANAGED_DELIVERY_MIGRATION` **after** `REPORTING_LEDGER_MIGRATION`, explicitly construct the Core store with `managedDelivery: true`, create a `PostgresReportingManagedDeliveryStore`, and pass both stores with a destination adapter to `createReportingManagedDeliveryRuntime`. The async factory proves the stores share one authority and validates the RC3 tier wiring before returning it. It advertises `managed_delivery` only when an immutable binding, delivery, bounded resource reading, generation-fenced revocation, and at least one verification profile are installed. The advertised automated recovery window must be at least the widest installed managed Core configuration recovery window. It advertises `reconciled_billing` and `receipt_task` only when an authenticated consumer resolver and canonical-digest verification are also installed.

package/docs/guides/REPORTING-OPERATIONS.md

@@ -72,6 +72,65 @@ different operators own tenant partitions. For Reconciled Billing offerings,
 provide `obligatedConsumers` from a trusted authorization roster. A missing or
 incomplete roster cannot safely mark a billing obligation reconciled.
 
+## Adopting row storage, retention and the change feed
+
+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.
+
+1. **Row storage.** Apply `REPORTING_ROW_STORAGE_MIGRATION` (PostgreSQL 13+),
+   or pass `rowStorage` to the production service, which adds it to
+   `setup.migrations`. Roll out with `rowStorage` set. New revisions store
+   verified chunks. Existing revisions keep their inline rows, and every
+   binary built with row storage reads both forms. Do not run a writer older
+   than this release once chunked revisions exist: it cannot read them.
+2. **Existing inline rows (optional).** Run `migrateInlineRows` in bounded
+   batches from a maintenance job until it returns no cursor. Alert on any
+   `quarantined` IDs: those revisions no longer reproduce their committed
+   binding and are left untouched for investigation. Then reclaim space with
+   `VACUUM FULL` or an online repack in a maintenance window.
+3. **Object storage.** Create a dedicated private bucket, container or prefix
+   for rows, separate from Managed Delivery buckets. Configure the binding in
+   host code and run `runReportingRowObjectProviderConformanceV1` against a
+   test prefix first. S3 bucket versioning and Azure blob versioning are
+   **required**, and the providers' probes refuse unversioned buckets and
+   accounts: deletes must be fenced to one write, and ETags are content-derived,
+   so an ETag-pinned delayed delete (for example an intent sweep) could remove a
+   replacement object re-created with identical bytes at the same key. Deleting
+   a specific `VersionId` permanently removes that version (no delete marker),
+   so retention still frees storage. Do not
+   attach lifecycle rules that can delete live rows sooner than
+   `max(statusRetentionDays, recordRetentionDays)` plus the restatement window.
+   The GCS probe refuses them; for S3 and Azure, policies outside the client's
+   view are the operator's responsibility.
+4. **Change feed.** Apply `REPORTING_LEDGER_CHANGES_MIGRATION` (PostgreSQL 13+)
+   or pass `changeFeed`. Register each durable consumer with
+   `saveFeedConsumerCursor`, and size `maxFeedHoldDays` so one stalled consumer
+   cannot hold the table indefinitely.
+5. **Warehouse sink.** Apply `REPORTING_WAREHOUSE_SINK_MIGRATION`, create the
+   tables, and the `current_rows` view, then schedule `runOnce`. Point analysts
+   at `current_rows`.
+6. **Retention.** Enable `retention` last, after confirming the advertised
+   `status_retention_days` is the window you intend to keep. Retirement deletes
+   rows and ledger records for whole periods and cannot be undone. Keep backups
+   for any longer audit requirement.
+
+Alert on these row-storage signals:
+
+- `ROWS_INTEGRITY_FAILED` or `ROWS_UNAVAILABLE` from reads. These are never
+  normal, and buyers see `SERVICE_UNAVAILABLE` for the affected revision.
+- A growing count of `adcp_reporting_row_write_intents` in `sweeping` state,
+  or `sweepRowWriteIntents` reporting failures. Provider deletes are failing.
+- `retireExpiredPeriods` returning `failed` IDs. Usually a binding was removed
+  from configuration while revisions still reference it; keep retired bindings
+  configured.
+- `ReportingChangeCursorExpiredError` in a consumer. That consumer fell behind
+  retention and must resynchronize from `listCurrentRevisions`.
+- A non-empty `missing` from the warehouse sink's `runOnce()`. The sink was down
+  longer than `maxFeedHoldDays`, retention stopped waiting for it, and the
+  warehouse lacks those revisions. Backfill them or accept the gap, and keep
+  `maxFeedHoldDays` above your longest tolerated sink outage.
+
 ## Service objectives and alerts
 
 Choose targets stricter than contractual delivery SLAs. A reasonable starting
@@ -146,7 +205,17 @@ Quarterly, restore into an isolated environment and verify:
 - notification recovery resumes without duplicate logical events;
 - buyer cursors/checkpoints resume and duplicate notification keys remain deduped;
 - a new lease fences an expired owner;
-- sampled manifest and canonical-content digests still verify.
+- sampled manifest and canonical-content digests still verify;
+- sampled chunked revisions read back through `getRevision`, including rows in
+  object-storage bindings.
+
+Row objects live outside the database. A database restore and the matching
+row buckets must come from the same point in time, or revisions committed
+after the bucket snapshot read as `ROWS_UNAVAILABLE`. A restored replica of
+the same authority keeps its installation identity. An independently writable
+clone, such as staging restored from production, must mint a new
+`adcp_persistence_installation` row and use new bindings before it writes or
+sweeps, so it can never delete production objects.
 
 After regional failover, fence the old primary before enabling writers. Ensure
 database time is healthy, then start canary workers and watch lease generation,
@@ -177,6 +246,12 @@ Disable notification-triggered acceleration if necessary, retain dedupe rows,
 and repair the authenticated seller/principal registry before resuming. Never
 choose an account based only on an untrusted webhook body.
 
+Row-storage integrity failure: stop serving the affected scope and do not
+re-upload over the recorded object. Compare the stored object's bytes and
+version with the chunk manifest, restore the exact recorded version from bucket
+versioning or backups, and verify by reading the revision through `getRevision`.
+Never edit a chunk manifest or digest to match the stored bytes.
+
 Clock skew: remove the host from service. Lease and event times use PostgreSQL
 where correctness needs a shared clock, while provider deadlines and process
 timeouts still depend on healthy host clocks.

package/docs/guides/WEB-OAUTH.md

@@ -69,10 +69,57 @@ Auth0 `audience`. With storage, overrides persist/reuse on omission; successful
 `PendingWebFlowStore`: `put(flow)` and atomic `consume(state)`, e.g. PostgreSQL
 `DELETE ... WHERE state = $1 AND expires_at > now() RETURNING payload`, or Redis
 `SET pending:flow:<state> <payload> EX 600 NX` then `GETDEL`. SELECT/DELETE races
-permit replay. Store contract tests: `test/lib/oauth-web-flow.test.js`.
+permit replay. Check your store with `assertPendingWebFlowStoreRoundTrip` (below).
 `DEFAULT_WEB_FLOW_TTL_MS` is 10 minutes; shorten as needed. `InMemoryPendingFlowStore` is
 test/dev-only; restarts lose flows. Encrypt PKCE verifiers at rest across trust boundaries.
 
+Use `serializePendingWebFlow` and `parsePendingWebFlow` from `@adcp/sdk/auth`
+for the stored payload. The parser validates SDK-owned fields, revives `createdAt`
+and `expiresAt` as `Date` values, and returns `null` for malformed input. It accepts
+JSON strings and decoded JSON values such as `pg`'s `jsonb` payloads. It preserves
+unknown fields and all client metadata, including `issuer` and `client_secret`.
+Do not narrow the persisted shape to today's fields: a hand-written schema that
+strips new optional fields can type-check while breaking sign-in after an SDK upgrade.
+
+```ts
+import { parsePendingWebFlow, serializePendingWebFlow } from '@adcp/sdk/auth';
+import { assertPendingWebFlowStoreRoundTrip } from '@adcp/sdk/testing';
+
+// In put(flow), serialize before encrypting and inserting with duplicate rejection:
+const payload = serializePendingWebFlow(flow);
+
+// In consume(state), decrypt the payload returned by atomic get-and-delete:
+function restoreConsumedFlow(state: string, decryptedPayload: unknown) {
+  const restored = parsePendingWebFlow(decryptedPayload);
+  return restored && restored.state === state && restored.expiresAt.getTime() > Date.now()
+    ? restored
+    : null;
+}
+
+// In CI, use a disposable instance of your production store on each SDK upgrade:
+await assertPendingWebFlowStoreRoundTrip(pendingFlowStore);
+// Stores with application-owned constraints can supply valid fixture values:
+await assertPendingWebFlowStoreRoundTrip(pendingFlowStore, {
+  agentId: testAgentId,
+  carry: { user_id: testUserId, nested: { values: ['one', 2, null] } },
+});
+```
+
+The helper checks every current SDK field (including nested `carry` and issuer-bound
+client secrets), Date revival, missing states, single use, expired rows, duplicate
+rejection, and concurrent consume. It also checks null/absent snapshots, clear actions,
+public clients, registration metadata, and unknown extensions. Stores may reject
+already-expired inserts; the helper still checks that consumption returns `null`.
+Its fixture is exhaustive at SDK build time, including optional flow and client
+information fields. The concurrency check is a smoke test; the backend must
+provide atomic deletion across processes. Use JSON-serializable `carry` and validate
+its application-owned contents separately. Keep absent optional fields absent when
+hydrating rows; an undefined-valued own `resourceOverrideSnapshot` can trigger the
+callback's concurrent-edit guard. The store still owns encryption of PKCE
+and client secrets, TTL, duplicate rejection, atomic consume, and binding the payload's
+`state` to its storage key. The parser does not filter expired flows or establish
+issuer trust; `completeWebOAuthFlow` also enforces expiry and issuer binding.
+
 Optional `agentStorage` (`OAuthConfigStorage`): callback loads the pending row's
 agent ID. Without it, completion
 returns `persisted: false` for application persistence. Preserve the issuer guide's

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
-> Generated at: 2026-10-08
-> Library: @adcp/sdk v15.4.0
+> Generated at: 2026-10-09
+> Library: @adcp/sdk v15.6.0
 > 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.
@@ -136,6 +136,8 @@ A submitted mutation must settle before it can be controlled; retain the task ha
 
 **Existing applications.** The [thin existing-platform recipe](./guides/EXISTING-PLATFORM.md) shows one SDK task inside application-owned auth and transactions, durable submitted-task recording, the error/cancellation matrix, non-blocking bounded diagnostics, and same-instance capability evidence reuse with `AgentClient.createWithCapabilityPreflight()` (or the lower-level `getCapabilityEvidenceScope()` + `primeCapabilities()` pair). The SDK 14 release represented by the checkout, its registry integrity check, peer/runtime ranges, wire pin, and a historical rc.33/rc.35 → rc.36 example are generated in [the release worksheet](./migration-14.x-rc-worksheet.md).
 
+**Request-local clients.** Share endpoint and capability discovery with an application-owned `discoveryCache` and explicit authorization identity. The public `withMCPConnectionScope()` groups a workflow's MCP calls onto reusable sessions; correlation headers, cancellation and deadlines remain per call. See [Discovery cache and session reuse](./guides/DISCOVERY-CACHE-AND-SESSION-REUSE.md).
+
 ## Canonical Reference Resolver
 
 `format_schema` and `platform_extensions` references use immutable `{ uri, digest }` pointers. Use `createCanonicalReferenceResolver` from `@adcp/sdk/canonical-references` instead of raw fetches; it applies SSRF-safe DNS-pinned fetches, redirect blocking, timeout/body caps, SHA-256 verification, structured non-throwing statuses, and bounded policy-scoped LRU caching. The zero-argument cache holds at most 64 entries / 32 MiB estimated retained data; use `createCanonicalReferenceCache({ maxEntries, maxBytes })` to tune the per-resolver budget or inject a fully caller-owned cache.

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@15.4.0` |
-| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@15.4.0 dist.integrity` |
+| Exact npm package | `@adcp/sdk@15.6.0` |
+| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@15.6.0 dist.integrity` |
 | Node.js runtime | `^20.19.0 || >=22.12.0` |
 | Default AdCP wire release | `3.2.3` |
 | 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` |
@@ -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@15.4.0'
-npm view '@adcp/sdk@15.4.0' dist.integrity
+npm install --save-exact '@adcp/sdk@15.6.0'
+npm view '@adcp/sdk@15.6.0' dist.integrity
 ```
 
 ### Required and optional peers
@@ -32,6 +32,8 @@ 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 |