@adcp/sdk 15.5.0 → 15.7.0

package/docs/guides/REPORTING-LEDGER.md

@@ -307,6 +307,11 @@ await store.readyRowStorage();
 - 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.
+- An exact `get_media_buy_delivery` read of an unknown, unauthorized, expired or
+  compacted revision, or with a tampered `pagination.cursor`, returns the same
+  nondisclosing `REFERENCE_NOT_FOUND` with `field: "reporting_revision_id"`
+  (not transient, so buyers do not retry), so a response never reveals whether a
+  revision exists for another account.
 - Managed Delivery claims hydrate PostgreSQL-stored rows automatically.
 
 To move existing inline rows into row storage, run the resumable migration in
@@ -376,6 +381,14 @@ await store.readyRowStorage();
 - 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.
@@ -417,6 +430,86 @@ 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
+`@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
@@ -425,6 +518,17 @@ 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
@@ -442,6 +546,90 @@ because the retired obligations no longer exist.
 always sweeps abandoned row uploads and expired cursor snapshots and
 checkpoints, and retires periods when retention is enabled.
 
+### Core-only setup with row storage, change feed and retention
+
+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
+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.
+
+```ts
+import {
+  PostgresReportingLedgerStore,
+  REPORTING_LEDGER_MIGRATION,
+  REPORTING_ROW_STORAGE_MIGRATION,
+  REPORTING_LEDGER_CHANGES_MIGRATION,
+} from '@adcp/sdk/reporting/ledger';
+import { createReliableReportingService } from '@adcp/sdk/reporting/service';
+
+// Apply the three migrations, then:
+const store = new PostgresReportingLedgerStore(pool, {
+  acknowledgeIsolatedDatabase: true,
+  rowStorage, // verified chunked rows in your object store
+  changeFeed: true, // host reads and consumer cursors
+});
+await store.readyRowStorage();
+
+const reporting = createReliableReportingService({
+  store,
+  statusRetentionDays: 90, // the commitment advertised to buyers; retention uses it
+  // ...adapters, contact, resolveSource, resolveCurrency, resolveCoverage
+  maintenance: {
+    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 });
+```
+
+`reporting.start()` runs maintenance on its first pass and then at most once per
+`maintenance.intervalMilliseconds`, after the tenant cycles, never on every
+cycle. A task that throws, or that resolves with `failed` items, goes to the
+scheduler's `onError` (or `logger.warn`) and never stops the loop; partial
+failures arrive as `ReportingMaintenancePartialFailureError`.
+
+If you run your own scheduler instead, call `reporting.runMaintenance({ signal })`.
+It returns one result per task and reports failures in the result rather than
+throwing:
+
+```ts
+for (const result of await reporting.runMaintenance()) {
+  if (result.status === 'failed') log.error(result.task, result.error);
+  else if (result.partialFailure) log.warn(result.partialFailure.message);
+}
+```
+
+Tasks, in order:
+
+| Task                  | Runs                                              | What it does                                                         |
+| --------------------- | ------------------------------------------------- | -------------------------------------------------------------------- |
+| `snapshot sweep`      | always                                            | Deletes expired cursor snapshots and checkpoints (1,000 per pass).   |
+| `row upload sweep`    | always                                            | Resolves abandoned object uploads (100 per pass); no-op without row storage. |
+| `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`. |
+
+Notes:
+
+- `maintenance` requires a `PostgresReportingLedgerStore` (or a store with the
+  same `retireExpiredPeriods`, `pruneChanges` and `sweepRowWriteIntents`
+  methods) 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
+  a period earlier than the retention you advertise. `recordRetentionDays` may
+  only lengthen it.
+- The snapshot sweep uses `store.sweepExpiredState()`. A custom store without
+  that method skips the task rather than failing.
+- Run it on every replica or on one: each task is bounded, resumable and safe
+  to run concurrently.
+- Enable `retention` last (see the adoption checklist in the
+  [operations guide](REPORTING-OPERATIONS.md#adopting-row-storage-retention-and-the-change-feed)).
+  Retirement cannot be undone.
+
 ### Host reads: current revisions and the change feed
 
 In-process consumers such as pacing, alerts and warehouse loaders read from the
@@ -478,9 +666,75 @@ await store.saveFeedConsumerCursor('pacing', page.cursor); // holds back pruning
   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,71 @@ 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.
+
+Running Core only, without the production service? Pass `maintenance` to
+`createReliableReportingService` so its scheduler (or `runMaintenance()`) does
+the retention, change-feed pruning and abandoned-upload sweeps the production
+service runs for you. See
+[Core-only setup](REPORTING-LEDGER.md#core-only-setup-with-row-storage-change-feed-and-retention).
+
+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 +211,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 +252,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-09
-> Library: @adcp/sdk v15.5.0
+> Library: @adcp/sdk v15.7.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.

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.5.0` |
-| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@15.5.0 dist.integrity` |
+| Exact npm package | `@adcp/sdk@15.7.0` |
+| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@15.7.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.5.0'
-npm view '@adcp/sdk@15.5.0' dist.integrity
+npm install --save-exact '@adcp/sdk@15.7.0'
+npm view '@adcp/sdk@15.7.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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "15.5.0",
+  "version": "15.7.0",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",
@@ -284,6 +284,16 @@
         "default": "./dist/lib/schemas/index.js"
       }
     },
+    "./schemas/browser": {
+      "import": {
+        "types": "./dist/lib/schemas/browser.d.mts",
+        "default": "./dist/lib/schemas/browser.mjs"
+      },
+      "require": {
+        "types": "./dist/lib/schemas/browser.d.ts",
+        "default": "./dist/lib/schemas/browser.js"
+      }
+    },
     "./compliance-fixtures": {
       "import": {
         "types": "./dist/lib/compliance-fixtures/index.d.mts",
@@ -419,6 +429,36 @@
         "types": "./dist/lib/reporting/gcs/index.d.ts",
         "default": "./dist/lib/reporting/gcs/index.js"
       }
+    },
+    "./reporting/s3": {
+      "import": {
+        "types": "./dist/lib/reporting/s3/index.d.mts",
+        "default": "./dist/lib/reporting/s3/index.mjs"
+      },
+      "require": {
+        "types": "./dist/lib/reporting/s3/index.d.ts",
+        "default": "./dist/lib/reporting/s3/index.js"
+      }
+    },
+    "./reporting/azure": {
+      "import": {
+        "types": "./dist/lib/reporting/azure/index.d.mts",
+        "default": "./dist/lib/reporting/azure/index.mjs"
+      },
+      "require": {
+        "types": "./dist/lib/reporting/azure/index.d.ts",
+        "default": "./dist/lib/reporting/azure/index.js"
+      }
+    },
+    "./reporting/bigquery": {
+      "import": {
+        "types": "./dist/lib/reporting/bigquery/index.d.mts",
+        "default": "./dist/lib/reporting/bigquery/index.mjs"
+      },
+      "require": {
+        "types": "./dist/lib/reporting/bigquery/index.d.ts",
+        "default": "./dist/lib/reporting/bigquery/index.js"
+      }
     }
   },
   "typesVersions": {
@@ -489,6 +529,9 @@
       "schemas": [
         "dist/lib/schemas/index.d.ts"
       ],
+      "schemas/browser": [
+        "dist/lib/schemas/browser.d.ts"
+      ],
       "compliance-fixtures": [
         "dist/lib/compliance-fixtures/index.d.ts"
       ],
@@ -542,6 +585,15 @@
       ],
       "reporting/gcs": [
         "dist/lib/reporting/gcs/index.d.ts"
+      ],
+      "reporting/s3": [
+        "dist/lib/reporting/s3/index.d.ts"
+      ],
+      "reporting/azure": [
+        "dist/lib/reporting/azure/index.d.ts"
+      ],
+      "reporting/bigquery": [
+        "dist/lib/reporting/bigquery/index.d.ts"
       ]
     }
   },
@@ -684,6 +736,7 @@
     "ci:validate": "node scripts/ci-validate.js",
     "ci:quick": "npm run format:check && npm run typecheck && npm run build:lib && npm test",
     "test:zod-openapi-portability": "node --test test/lib/zod-openapi-portability.test.js",
+    "test:schemas-browser": "node --test-timeout=60000 --test test/lib/schemas-browser.test.js",
     "ci:schema-check": "npm run sync-schemas && npm run generate-types && npm run generate-registry-types -- --sync && git diff --exit-code -I '// Generated at:' src/lib/types/ src/lib/agents/ src/lib/media-buy/action-metadata.generated.ts src/lib/media-buy/update-fields.generated.ts src/lib/registry/types.generated.ts schemas/registry/registry.yaml || (echo '⚠️  Generated files are out of sync. Run: npm run sync-schemas && npm run generate-types && npm run generate-registry-types -- --sync' && exit 1)",
     "ci:codegen-strict": "tsx scripts/check-no-loose-oneof.ts",
     "ci:docs-check": "npm run generate-agent-docs && npm run generate-release-worksheet && git diff --exit-code -I '> Generated at:' docs/llms.txt docs/TYPE-SUMMARY.md docs/migration-14.x-rc-worksheet.md || (echo '⚠️  Generated docs are out of sync. Run: npm run generate-agent-docs && npm run generate-release-worksheet' && exit 1)",
@@ -746,6 +799,8 @@
   },
   "peerDependencies": {
     "@a2a-js/sdk": "^1.0.1",
+    "@aws-sdk/client-s3": "^3.700.0",
+    "@azure/storage-blob": "^12.23.0",
     "@google-cloud/storage": "^7.22.0 || ^8.2.0",
     "@modelcontextprotocol/sdk": "^1.31.0",
     "@opentelemetry/api": "^1.0.0",
@@ -753,6 +808,12 @@
     "zod": "^4.1.5"
   },
   "peerDependenciesMeta": {
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@azure/storage-blob": {
+      "optional": true
+    },
     "@google-cloud/storage": {
       "optional": true
     },
@@ -767,6 +828,8 @@
     "@a2a-js/sdk": "^1.0.1",
     "@apidevtools/json-schema-ref-parser": "^15.5.2",
     "@arethetypeswrong/cli": "^0.18.5",
+    "@aws-sdk/client-s3": "^3.1147.0",
+    "@azure/storage-blob": "~12.32.0",
     "@changesets/cli": "^3.0.3",
     "@commitlint/cli": "^20.5.3",
     "@commitlint/config-conventional": "^20.5.3",