@adcp/sdk 15.8.0 → 15.9.0

package/docs/guides/REPORTING-OPERATIONS.md

@@ -111,7 +111,8 @@ service runs for you. See
    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
+   `saveFeedConsumerCursor` (checkpoints are forward-only; pass `{ rewind: true }`
+   to move a consumer back), 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
@@ -135,15 +136,25 @@ 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.
+  or `sweepRowWriteIntents` reporting failures. Provider deletes are failing;
+  failed intents back off (one minute, doubling, capped at six hours) rather than
+  blocking others. `skippedUnconfigured` counts expired uploads whose binding this
+  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 `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.
-- `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`.
+- `retireExpiredPeriods` returning `failed` IDs or a non-empty `stuck` list.
+  Usually a binding was removed from configuration while revisions still
+  reference it; keep retired bindings configured. A failing period retries with
+  backoff (up to six hours) and does not block other periods; `stuck` lists
+  those that have failed five or more times, with their cause.
+- `ReportingChangeCursorExpiredError` (`code === 'CURSOR_EXPIRED'`) in a
+  consumer. Usually it fell behind retention and must resynchronize from
+  `listCurrentRevisions`. A first read with no cursor can also throw it when a
+  prune commits mid-read; retry it. A new warehouse sink stuck on it after such
+  a race recovers with `sink.reset()`.
 - 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
@@ -270,6 +281,19 @@ 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.
 
+Multi-transport managed delivery: when one runtime delivers through several
+transports behind the managed-delivery router, key alerts on the per-route
+worker counts (`deliveryFailuresByRoute`, `revocationFailuresByRoute`,
+`overdueByRoute`) instead of the totals, so one failing transport is not
+averaged away. A non-zero `~unrouted` count is a configuration problem, not a
+provider outage: a binding or destination authorization has no route (often a
+legacy authorization with no recorded transport and no `legacyDefault`). List
+those authorizations with `listDestinationAuthorizationsWithoutContract()`,
+then add the route or a `legacyDefault`. A startup probe failure names the
+failing route; fix that route's provider access before restarting, because
+offerings are not withdrawn at runtime. See "Multi-transport delivery with the
+router" in `REPORTING-LEDGER.md`.
+
 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.
@@ -289,3 +313,180 @@ timeouts still depend on healthy host clocks.
 For the optional GCS provider write-fence primitive and its bucket policy, inventory retention and cancellation requirements, see [Durable GCS reporting write fence](REPORTING-GCS-FENCE.md). Complete managed delivery integration remains a separate step.
 
 For complete GCS file-transfer delivery, private contracts and scoped buyer readers, see [Managed reporting delivery on GCS](REPORTING-GCS-MANAGED.md).
+
+## Live GCP validation
+
+`scripts/validate-reporting-gcp.mjs` runs the built SDK 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
+package, so run it from a repository checkout.
+
+What it checks:
+
+- **BigQuery warehouse sink** (`@adcp/sdk/reporting/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
+  and the JSON `row` column by query, that the load jobs exist in the
+  destination project and location under the deterministic job IDs, that a
+  crash after the rows load (an injected failing revisions load) replays with no
+  duplicate rows, and that `current_rows` returns one revision per obligation.
+  It also asserts (`PASS`/`FAIL`) that the sink sends no `labels` or
+  `jobTimeoutMs` inside `configuration.load`, where BigQuery silently drops
+  them, and that a job cancel addressed with the destination project and
+  location (what the sink sends when a load passes its client-side deadline) is
+  accepted by BigQuery.
+- **Overlapping runs** (`INFO`, never a failure). Two concurrent `runOnce()`
+  calls over one pending batch, and a deterministic reproduction of #3196: one
+  run reads its sink state, another completes the batch and a new revision
+  commits, then the first resumes. Without the fence the first run reloads
+  revisions the second already loaded (duplicate rows); with the fence from
+  PR #3197 it rejects as stale and nothing duplicates. Read the verdict in the
+  report; the exit status does not depend on it.
+- **Cross-project.** Set `GCP_CLIENT_PROJECT` to a project other than
+  `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,
+  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
+  back verified (full read, ranged page, a second store instance, and a replayed
+  commit that uploads nothing).
+
+Everything it creates carries a per-run id: a dataset named
+`<GCP_DATASET_PREFIX><run id>`, objects under `<GCS_PREFIX>/<run id>/`, and
+PostgreSQL schemas `adcp_validation_<run id>_*`. All of it is deleted in
+`finally` (and on Ctrl-C) unless `KEEP=1`. Deletion is limited to those names:
+the script refuses to delete a dataset without the prefix, an object outside
+the run prefix, or a schema without the run id.
+
+### Setup
+
+```bash
+npm ci && npm run build
+# Optional peers; --no-save leaves package.json alone.
+npm install --no-save @google-cloud/bigquery @google-cloud/storage
+```
+
+Use Application Default Credentials (workload identity,
+`gcloud auth application-default login`, or `GOOGLE_APPLICATION_CREDENTIALS`).
+The script never reads, writes or prints credentials, and it redacts the
+PostgreSQL URL and bearer tokens from anything it prints. If a peer package is
+missing it prints the install command and exits with status 2.
+
+| Variable                                                             | Required                 | Meaning                                                                                                                                                              |
+| -------------------------------------------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `REPORTING_LEDGER_PG_URL`                                            | yes                      | PostgreSQL the ledger runs on. The role must be able to create and drop schemas.                                                                                     |
+| `GCP_BQ_PROJECT`                                                     | unless `--skip-bigquery` | Destination project for the temporary dataset.                                                                                                                       |
+| `GCP_BQ_LOCATION`                                                    | no (`US`)                | Dataset and job location.                                                                                                                                            |
+| `GCP_CLIENT_PROJECT`                                                 | no                       | The BigQuery client's default project (billing project for queries and DDL). Set it different from `GCP_BQ_PROJECT` to exercise the cross-project path.             |
+| `GCP_DATASET_PREFIX`                                                 | no (`adcp_sink_validation_`) | Dataset name prefix.                                                                                                                                     |
+| `GCS_BUCKET`                                                         | unless `--skip-gcs`      | Bucket under test. Its policy must satisfy the row-provider probe.                                                                                                   |
+| `GCS_PREFIX`                                                         | no (`adcp-reporting-validation`) | A prefix you own for the test; a unique run folder is created beneath it.                                                                                    |
+| `KEEP=1`                                                             | no                       | Keep the dataset, objects and schemas, and print how to remove them.                                                                                                 |
+| `ADCP_SDK_ROOT`                                                      | no                       | Another built checkout whose `dist/` is tested (see below).                                                                                                          |
+| `--yes` or `CONFIRM=1`                                               | yes                      | Acknowledge the preflight; without it nothing is created and the exit status is 2.                                                                                   |
+| `--skip-bigquery`, `--skip-gcs` (or `SKIP_BIGQUERY=1`, `SKIP_GCS=1`) | no                       | Skip a section.                                                                                                                                                      |
+
+The preflight prints the identity ADC resolves to, the projects, location,
+bucket, prefix and dataset name before anything is created.
+
+### Required IAM
+
+- **Destination project** (or the dataset, once it exists): BigQuery Data
+  Editor (`roles/bigquery.dataEditor`; it includes `bigquery.datasets.create`
+  and table create and read) and BigQuery Job User (`roles/bigquery.jobUser`;
+  load jobs are created here). The creator of a dataset owns it, which covers
+  the forced delete in cleanup; if your organization strips that, grant
+  `roles/bigquery.dataOwner` instead. If reading job metadata is denied, add
+  `roles/bigquery.resourceViewer` (`bigquery.jobs.get`).
+- **Client project**, when it differs: BigQuery Job User, because the DDL and
+  verification queries run as jobs there.
+- **GCS**: Storage Object Admin (`roles/storage.objectAdmin`) on the test
+  prefix, with an IAM condition such as
+  `resource.name.startsWith("projects/_/buckets/BUCKET/objects/PREFIX/")`, plus
+  `storage.buckets.get` for the probe (for example
+  `roles/storage.legacyBucketReader`, or a custom role holding only
+  `storage.buckets.get`). Object Admin alone does not include
+  `storage.buckets.get`.
+
+### Running it
+
+Against current `main`:
+
+```bash
+git checkout main && git pull && npm ci && npm run build
+npm install --no-save @google-cloud/bigquery @google-cloud/storage
+export REPORTING_LEDGER_PG_URL=postgres://...   # a scratch database
+export GCP_BQ_PROJECT=dest-project GCP_CLIENT_PROJECT=billing-project GCP_BQ_LOCATION=US
+export GCS_BUCKET=my-test-bucket GCS_PREFIX=adcp-reporting-validation
+npm run validate:reporting-gcp -- --yes
+```
+
+Against a pull request branch (for example #3197), keep running the script from
+`main` and point it at a second built checkout, so a branch cut before this
+script existed still works:
+
+```bash
+git fetch origin pull/3197/head:pr-3197
+git worktree add ../adcp-client-pr-3197 pr-3197
+(cd ../adcp-client-pr-3197 && npm ci && npm run build)
+ADCP_SDK_ROOT=../adcp-client-pr-3197 npm run validate:reporting-gcp -- --yes
+```
+
+The same environment applies. The run ends with a `PASS`, `FAIL` and `INFO`
+report and a markdown block (project and bucket names masked) to paste into
+the PR. The exit status is 0 with no `FAIL`, 1 with any `FAIL`, and 2 for a
+configuration problem or a missing `--yes`. Results of the overlap probes are
+`INFO` on purpose: on `main` expect the stale-run probe to report duplicates,
+and on PR #3197 expect it to report none.
+
+`test/lib/reporting-gcp-validation-pg.test.js` drives the script's core against
+in-memory BigQuery and Storage doubles and a real PostgreSQL, so the logic,
+reporting and cleanup safety stay covered without credentials. It proves nothing
+about real BigQuery or GCS behavior.
+
+### The Python SDK's equivalent
+
+The Python SDK (`adcp-client-python`, package `adcp`) has the same GCS row
+provider and the same conformance runner: `create_gcs_reporting_row_object_provider_v1`
+in `adcp.reporting.ledger.row_storage_gcs` and
+`run_reporting_row_object_provider_conformance_v1` in
+`adcp.reporting.ledger.row_storage_object`, with the same bucket policy rules.
+Install `pip install 'adcp[reporting-gcs]'`, then run the conformance against the
+same bucket and prefix as above (it writes and deletes only
+`$GCS_PREFIX/conformance/<uuid>.jsonl`):
+
+```bash
+python - <<'PY'
+import asyncio, os
+from google.cloud import storage
+from adcp.reporting.ledger.row_storage_gcs import create_gcs_reporting_row_object_provider_v1
+from adcp.reporting.ledger.row_storage_object import run_reporting_row_object_provider_conformance_v1
+
+async def main():
+    provider = create_gcs_reporting_row_object_provider_v1(storage=storage.Client())
+    passed = await run_reporting_row_object_provider_conformance_v1(
+        provider,
+        location={"bucket": os.environ["GCS_BUCKET"]},
+        prefix=os.environ.get("GCS_PREFIX", "adcp-reporting-validation"),
+    )
+    print("PASS", passed)
+
+asyncio.run(main())
+PY
+```
+
+Python has no BigQuery warehouse sink. A live JavaScript to Python interop run
+against GCS is not possible with the existing interop test: the Python test
+(`tests/conformance/reporting/test_reporting_row_storage_interop_pg.py`) and its
+JavaScript driver (`tests/interop/reporting_row_storage_js_driver.cjs`) both
+hard-code the filesystem provider and a directory bucket root, and the
+cross-SDK row-storage fixtures replay on a filesystem too. Running it on GCS
+would need both drivers changed to build an object binding with
+`provider: 'gcs'` and `location: { bucket }` (same prefix, deployment namespace
+and binding definition on both sides). The optional live GCS controls in
+`scripts/reporting-interop/GCS.md` exercise the Managed Delivery evidence
+readers, not row storage.

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
-> Generated at: 2026-10-11
-> Library: @adcp/sdk v15.8.0
+> Generated at: 2026-10-13
+> Library: @adcp/sdk v15.9.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.
@@ -1575,7 +1575,7 @@ Flow: `get_products → create_media_buy → update_media_buy → get_media_buys
 Flow: `sync_accounts → create_media_buy → update_media_buy → get_media_buys → update_media_buy`
 
 **Seller handles typed proposal negotiation with constraints, product changes, and alternatives** — Verifies the AdCP 3.2 typed negotiation lifecycle: capability-gated constraint satisfaction, product changes, digest-verified alternatives, partial invariant, immutable lineage, finalize atomicity, and idempotent replay through refine_proposals.
-Flow: `get_adcp_capabilities → sync_accounts → get_products → refine_proposals → accept_proposal → refine_proposals`
+Flow: `get_adcp_capabilities → sync_accounts → request_proposals → refine_proposals → accept_proposal → refine_proposals`
 
 **Vendor-metric external catalog precondition** — Exercises the 3.1 SHOULD-window behavior for vendor_metric goals whose metric_id is absent from a seeded measurement.metrics[] catalog.
 Flow: `sync_accounts → comply_test_controller → create_media_buy`
@@ -1864,7 +1864,7 @@ Flow: `comply_test_controller`
 **OAuth discovery and metadata consistency** — Capability-gated evaluation of an agent's RFC 9728 protected-resource metadata and the complete RFC 8414 authorization-server graph it advertises.
 Flow: `get_adcp_capabilities`
 
-**Signed requests — RFC 9421 transport-layer verification** — Agent verifies RFC 9421 HTTP Signatures on incoming AdCP requests per the 3.1-compatible transport-layer profile. Universal capability-gated storyboard — runs for any agent advertising `request_signing.supported: true` regardless of `supported_protocols`. Graded against the legacy wire suite covering every 3.1 checklist step and canonicalization-edge rule.
+**Signed requests — RFC 9421 transport-layer verification** — Agent verifies RFC 9421 HTTP Signatures on incoming AdCP requests per the 3.1-compatible transport-layer profile. Universal capability-gated storyboard — runs for any agent advertising `request_signing.supported: true` regardless of `supported_protocols`. Graded against the legacy wire suite covering every 3.1 checklist step and canonicalization-edge rule; a verifier advertising `covers_content_digest: \
 Flow: `get_adcp_capabilities`
 
 **Trusted Match publisher authentication rejection** — Verifies that a TMP router deployment rejects schema-valid Context Match and Identity Match requests with absent or invalid publisher authentication using HTTP 401 and a WWW-Authenticate challenge.

package/docs/migration-12-to-13.md

@@ -391,6 +391,15 @@ Each `CanonicalFormatLegacyRoute` contains `product_id`, the stable
 resolver to `AgentClient` or `createAdcpServerFromPlatform()` without changing
 the existing resolver callback contract.
 
+Routes built with `legacyRoutesForProduct()` from products returned by
+`getProducts()` also record `seller_declared`. It is `false` when the SDK derived
+the option from a seller's legacy `format_ids`; such a route also carries
+`canonical_selector`, the `format_kind` + `params` that a canonical-wire write
+sends in place of the SDK-minted `format_option_id`, which the seller cannot
+resolve. An `AgentClient` given a resolver rebuilt from these routes applies
+that rewrite in another process, as it does after its own discovery. Routes
+without `seller_declared` leave canonical writes unchanged.
+
 Compatibility consumers that must retain top-level `format_ids[]` while
 publishing URL-free canonical declarations can use the additive projection:
 

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

@@ -11,18 +11,18 @@ below as the publication/deployment gate.
 
 | Fact | Value |
 | --- | --- |
-| Exact npm package | `@adcp/sdk@15.8.0` |
-| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@15.8.0 dist.integrity` |
+| Exact npm package | `@adcp/sdk@15.9.0` |
+| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@15.9.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` |
+| Default AdCP wire release | `3.2.4` |
+| Maintained wire releases | `v2.5`, `v2.6`, `v3`, `3.0.0`, `3.0`, `3.0.1`, `3.0.2`, `3.0.3`, `3.0.4`, `3.0.5`, `3.0.6`, `3.0.7`, `3.0.8`, `3.0.9`, `3.0.10`, `3.0.11`, `3.0.12`, `3.0.13`, `3.0.14`, `3.0.15`, `3.0.16`, `3.0.17`, `3.0.18`, `3.0.19`, `3.0.20`, `3.0.21`, `3.0.22`, `3.0.23`, `3.0.24`, `3.0.25`, `3.1.0`, `3.1`, `3.1.1`, `3.1.2`, `3.1.3`, `3.1.4`, `3.1.5`, `3.1.6`, `3.1.7`, `3.1.8`, `3.1.9`, `3.1.10`, `3.1.11`, `3.1.12`, `3.1.13`, `3.1.14`, `3.1.15`, `3.1.16`, `3.1.17`, `3.1.18`, `3.1.19`, `3.1.20`, `3.1.21`, `3.1.22`, `3.1.23`, `3.1.24`, `3.2.1`, `3.2`, `3.2.2`, `3.2.3`, `3.2.4` |
 | Canonical migration notes | [SDK 15 OAuth](./migration-oauth-issuer-bindings.md), [issuer-binding and storage](./guides/OAUTH-ISSUER-BINDING.md); historical [13.x → 14](./migration-13-to-14.md) |
 
 Install exact production inputs rather than a moving range or dist-tag:
 
 ```bash
-npm install --save-exact '@adcp/sdk@15.8.0'
-npm view '@adcp/sdk@15.8.0' dist.integrity
+npm install --save-exact '@adcp/sdk@15.9.0'
+npm view '@adcp/sdk@15.9.0' dist.integrity
 ```
 
 ### Required and optional peers
@@ -63,7 +63,7 @@ ESM example:
 import { getCanonicalToolValidator } from '@adcp/sdk/schemas';
 
 const validate = getCanonicalToolValidator('get_reporting_status', 'sync', {
-  adcpVersion: '3.2.3',
+  adcpVersion: '3.2.4',
 });
 if (!validate) throw new Error('Requested protocol schema is unavailable');
 
@@ -86,7 +86,7 @@ CommonJS uses the same packed-artifact export:
 ```js
 const { getCanonicalToolValidator } = require('@adcp/sdk/schemas');
 const validate = getCanonicalToolValidator('get_reporting_status', 'sync', {
-  adcpVersion: '3.2.3',
+  adcpVersion: '3.2.4',
 });
 if (!validate) throw new Error('Requested protocol schema is unavailable');
 if (validate({ status: 'completed', view: 'summary' })) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "15.8.0",
+  "version": "15.9.0",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",
@@ -610,7 +610,7 @@
     ".claude-plugin/**/*",
     "compliance/cache/3.0.25/**/*",
     "compliance/cache/3.1.24/**/*",
-    "compliance/cache/3.2.3/**/*",
+    "compliance/cache/3.2.4/**/*",
     "ADCP_VERSION",
     "docs/README.md",
     "docs/TYPE-SUMMARY.md",
@@ -719,6 +719,7 @@
     "check:package-size": "node scripts/check-package-size.mjs",
     "check:publish-protocol-artifacts": "node scripts/check-publish-protocol-artifacts.mjs",
     "verify:package": "node scripts/verify-package.mjs",
+    "validate:reporting-gcp": "node scripts/validate-reporting-gcp.mjs",
     "check:adopter-types": "tsx scripts/check-adopter-types.ts",
     "check:adopter-types-narrow": "tsx scripts/check-adopter-types-narrow.ts",
     "sync-version": "tsx scripts/sync-version.ts",
@@ -878,7 +879,7 @@
     },
     "minimatch": "^10.2.1"
   },
-  "adcp_version": "3.2.3",
+  "adcp_version": "3.2.4",
   "sideEffects": [
     "**/default-invariants.*"
   ]