@adcp/sdk 15.8.1 → 15.9.1

package/docs/guides/REPORTING-LEDGER.md

@@ -565,6 +565,31 @@ 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.
 
+A period whose deletes fail (a removed binding, a permanent provider error)
+stays `retiring` and is retried with backoff rather than on every pass. The
+tombstone records `attempts`, `next_attempt_at` and `last_failure`; the wait
+starts at one minute, doubles per failure and is capped at six hours. Periods
+still backing off are skipped. Ready retries go ahead of fresh periods for up to
+half of each pass (rounded up) and only fill slots fresh periods leave empty, so
+a retry backlog still drains at full speed when nothing else is eligible and a
+few stuck periods cannot stop others from retiring (each leaves the head of the
+queue for its backoff after one failed attempt). The result reports `failed` and `failures` for this pass,
+`deferred` for periods backing off, and `stuck` (up to 20, with `attempts` and
+`cause`) for periods that have failed five or more times. The maintenance helper
+passes `stuck` and `deferred` to `onError`. Re-apply `REPORTING_LEDGER_MIGRATION`
+before upgrading; it adds the three tombstone columns idempotently.
+
+`sweepRowWriteIntents` backs off the same way (`sweep_attempts`, `next_sweep_at`,
+added idempotently by `REPORTING_ROW_STORAGE_MIGRATION`) and takes intents that
+never failed first. An intent with objects to delete through a binding this host
+does not configure is left untouched, since a host that configures it can finish
+the sweep. The result counts `swept`, `objectsDeleted`, `failed` (this pass),
+`skippedUnconfigured`, `deferred` and `overdue`; the last three describe what is
+still waiting after the pass. `overdue` counts intents expired for longer than
+`overdueAfterSeconds` (default 24 hours): no host is sweeping them and their
+objects are leaking, so check that some host configures every binding you have
+used.
+
 `createPostgresReliableReportingProductionService` accepts
 `retention: { enabled: true, recordRetentionDays?, limit? }`. Its scheduler
 always sweeps abandoned row uploads and expired cursor snapshots and
@@ -791,11 +816,52 @@ await store.saveFeedConsumerCursor('pacing', page.cursor); // holds back pruning
   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.
+  never skipped. The account feed applies the same guard: a page ends before the
+  first change whose transaction has not finished (`xid` at or above the reading
+  snapshot's `xmin`), so the cursor never passes a change that commits late. The
+  page is cut there rather than filtered, because seq order and xid order can
+  differ and a filter would hand out a later change while skipping an earlier
+  one it excluded. The cost is that any older open transaction on the cluster,
+  including an idle one in another database, holds both kinds of feed back until
+  it ends; keep transactions short. An empty page therefore means either caught
+  up or held back, so poll again rather than treating it as the end of the feed.
+- **A ledger database has exactly one writer SDK.** The store writes each change
+  row under the account advisory lock, taking the sequence value only after it,
+  so per-account `seq` order equals commit order. The in-flight guard above is
+  defense in depth, not a substitute: a second SDK (for example a Python
+  deployment, or a hand-written writer) that takes a different lock key, or
+  writes change rows outside the account lock, can allocate a lower `seq` that
+  commits after a higher one. The guard narrows that window but cannot close it
+  for every interleaving, so run one writer SDK per ledger database and give
+  another SDK its own database. `pruneChanges` only deletes changes older than
+  `changeRetentionDays`, far longer than any transaction should stay open, and
+  consumer holds compare against cursors the feed itself returned, so neither
+  adds a new ordering assumption.
 - `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`.
+- A read with no cursor can throw `ReportingChangeCursorExpiredError` too. `changesAfter`
+  re-reads the retention horizon after the page, so a prune that commits during
+  a consumer's first read rejects that page instead of returning one that skips
+  the pruned changes. Host startup code must handle `CURSOR_EXPIRED` on a first
+  read the same way as on a saved cursor: retry (the new read starts at the later
+  horizon) or resynchronize from `listCurrentRevisions`. Match on
+  `error.code === 'CURSOR_EXPIRED'` rather than `instanceof`, which fails when
+  the store and your code load through different module formats (CJS and ESM).
+- Consumer checkpoints are forward-only. `saveFeedConsumerCursor(name, cursor)`
+  ignores a cursor behind the saved one in the same feed scope, so a delayed or
+  stale acknowledgment cannot pull the retention hold backward. It resolves
+  `true` when the checkpoint was written and `false` when it was ignored (an
+  equal position also resolves `false` with `{ refreshUnchanged: false }`). To
+  rewind a consumer on purpose, for example to replay changes, pass
+  `{ rewind: true }`; the saved position and retention hold move back to that
+  cursor (the write always applies, and the cursor is not checked against the
+  retention horizon, so it must still be inside the retained history). Without it a rewound
+  consumer would keep its old, newer hold, pruning could remove exactly what it
+  is about to read, and its next read would throw `CURSOR_EXPIRED`.
+  `removeFeedConsumer(name)` unregisters a consumer so it stops holding back
+  pruning; it resolves `true` when a registration was removed.
 - 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
@@ -818,10 +884,11 @@ import {
 } from '@adcp/sdk/reporting/bigquery';
 
 await pool.query(REPORTING_WAREHOUSE_SINK_MIGRATION); // after REPORTING_LEDGER_CHANGES_MIGRATION
+const bigquery = new BigQuery({ projectId: 'analytics-prod' }); // ADC / workload identity
 const sink = createBigQueryReportingWarehouseSinkV1({
   store, // PostgresReportingLedgerStore with changeFeed: true
   db: pool,
-  bigquery: new BigQuery({ projectId: 'analytics-prod' }), // ADC / workload identity
+  bigquery,
   name: 'warehouse',
   projectId: 'analytics-prod',
   datasetId: 'reporting',
@@ -829,11 +896,12 @@ const sink = createBigQueryReportingWarehouseSinkV1({
   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);
+setInterval(() => {
+  void sink.runOnce().catch(error => console.error('Warehouse run failed', error));
+}, 15 * 60_000);
 ```
 
 - Each run follows the change feed and reads every revision's rows through the
@@ -843,10 +911,107 @@ setInterval(() => void sink.runOnce(), 15 * 60_000);
   `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.
+  change-feed range. Before every submission the sink looks that job ID up in
+  the destination project and location: a job that finished cleanly counts as
+  loaded, a job that is pending or running is waited for (never uploaded
+  again), and only a missing job (404) is uploaded. A crash or timeout between a
+  load and the cursor commit therefore replays the same batch under the same
+  job ID without a second upload. An upload an earlier run abandoned at its
+  deadline is still running in the same process (the official client cannot
+  abort it), so the next run waits for it, within its own deadline, rather than
+  starting another, however long ago it started (that age includes the gap
+  between runs). If that wait outlasts the run's deadline it counts as a timeout
+  and the deadline grows. Only an upload still pending after 6 hours, the
+  largest deadline, is abandoned and replaced; BigQuery refuses a duplicate job
+  ID, so a replacement can never load the batch twice. A job that finished with
+  an error is retried under a new attempt for that table only. Deadline and
+  timeout errors name the table (`rows` or `revisions`, and its ID), the
+  deadline in force and that table's timeout count, never a file path or
+  credential.
+- `projectId` scopes both load submission and replay status checks. When it is
+  omitted, both use the BigQuery client's default project. Each replica must
+  be able to read the BigQuery jobs submitted by the other replicas. Set
+  `location` for any dataset outside the US and EU multi-regions: BigQuery
+  answers a job lookup without the right location with 404, and the sink then
+  cannot find the jobs it created.
+- `loadTimeoutMilliseconds` (default 10 minutes) is the base deadline for one
+  run's work on one load: uploading the file, or waiting for a job that is still
+  running. It bounds a run, not the job. BigQuery does not stop a load when the
+  client gives up (a cancel is accepted and the job finishes anyway), and it
+  refuses a resubmitted job ID only after the whole file is uploaded again, so
+  the sink never cancels and never relies on that refusal. When the deadline
+  passes, the run rejects with the plan retained and nothing advanced: the job
+  ID, the attempt and the cursor stay as they were, and the next run looks the
+  job up by its ID again. A job whose upload outlasted a deadline is created in
+  the background and is picked up by the next run with no second upload. Each
+  such timeout doubles that table's deadline for later runs (up to 6 hours).
+  The growth is kept with the plan in `planned_rows_timeouts` and
+  `planned_revisions_timeouts` (so it survives restarts and applies to every
+  replica, and clears when the batch commits), so an upload slower than the
+  deadline eventually gets enough time. Set the deadline above your slowest
+  expected load to avoid the extra runs. Only a job BigQuery reports as
+  finished with an error advances the attempt. A status check that times out
+  is bounded by the base deadline and does not grow it. Re-run
+  `REPORTING_WAREHOUSE_SINK_MIGRATION` after upgrading: it adds the two timeout
+  columns (a sink table without them rejects with a message saying so).
+  BigQuery's server-side `jobTimeoutMs` is not used: for a local-file load the
+  official client builds `configuration.load` from the load options and cannot
+  set job-level fields, and BigQuery silently drops `labels` and `jobTimeoutMs`
+  found inside `configuration.load`. (Staging the file in GCS and submitting the load with
+  `bigquery.createJob` can set both; the sink does not stage files.) For the
+  same reason the `labels` option has no effect (it warns once per process and
+  is deprecated). To attribute load cost, query
+  `` `region-<location>`.INFORMATION_SCHEMA.JOBS_BY_PROJECT `` (needs
+  `bigquery.jobs.listAll`; about 180 days of history), filtering on
+  `STARTS_WITH(job_id, 'adcp_rr_')` or on `destination_table`, and summing
+  `total_slot_ms` or `total_bytes_billed`.
+- Overlapping runs atomically claim one durable batch. Replays use that
+  batch's job IDs; attempts and cursor commits compare the full saved plan.
+  A stale run rejects without replacing another batch or rewinding either
+  the warehouse cursor or its feed checkpoint. Catch the rejection and retry
+  `runOnce()` on the next tick. Empty-feed cursor initialization uses the
+  same claim and commit rules. Replicas sharing a sink name must use the same
+  ledger database, feed scope, destination, location and row mapping. Use a new
+  name when that configuration changes. Independent ledgers loading into the
+  same BigQuery project must use distinct sink names, even if their destination
+  tables differ. An idle tick drains non-revision changes through the
+  same fenced checkpoint. An idle tick also recovers a failed acknowledgment
+  without refreshing an unchanged checkpoint. Failed loads and idle ticks
+  behind the deployment feed's transaction fence can still age out after
+  `maxFeedHoldDays`.
+- Feed reads recheck the retention horizon before returning a page. If pruning
+  overtakes the starting position during a read, `runOnce()` rejects with
+  `ReportingChangeCursorExpiredError` before committing the page.
+  The non-revision fallback preserves the first read's cursor, including on
+  initial startup. If retention overtakes the initial read, the sink records
+  that starting cursor before rejecting, so later ticks and restarted workers
+  continue to report the gap. This does not acknowledge the missing changes or
+  renew their retention hold. Resynchronize from current revisions before resuming.
+- A brand-new sink can hit that rejection from a harmless startup race: pruning
+  commits during its very first read, after the changes it lost were already
+  past retention and held by nobody. Every later tick then rejects with
+  `CURSOR_EXPIRED` because the sink keeps reporting that gap. Clear it with
+  `await sink.reset()`, which resets the sink to start from the oldest retained
+  change and unregisters its feed consumer (stop every worker with that sink
+  name first; do not edit `adcp_reporting_warehouse_sinks` by hand). `reset()`
+  refuses while a batch plan is retained, because that batch's BigQuery load
+  jobs may have succeeded; reconcile the plan against BigQuery, then call
+  `reset({ discardRetainedPlan: true })`. It does not touch the warehouse: a sink
+  that already loaded history reloads the retained revisions, so empty the
+  destination tables first (after stopping every worker and letting in-flight
+  uploads and jobs finish, since the sink never cancels a load) or use a new
+  sink name against new tables. Every
+  reset starts a new job ID generation, so reloaded batches submit fresh BigQuery
+  jobs instead of matching the finished jobs of the earlier history. Nothing holds
+  change retention between `reset()` and the first committed batch. If `reset()`
+  rejects after clearing the sink (it could not unregister the consumer), call
+  it again before restarting workers. Re-run `REPORTING_WAREHOUSE_SINK_MIGRATION`
+  after upgrading: it adds the `reset_generation` column.
+- Stop old sink workers before relying on these overlap guarantees. If an
+  earlier overlapping run left a plan whose starting cursor differs from the
+  committed cursor, the sink rejects it before loading. Reconcile the retained
+  plan, its BigQuery jobs and warehouse rows before repairing the checkpoint.
+  Do not discard the plan automatically: its load jobs may have succeeded.
 - 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.
@@ -855,7 +1020,9 @@ setInterval(() => void sink.runOnce(), 15 * 60_000);
   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`
+- `runOnce()` resolves with `{ idle, revisions, rows, missing }`. `idle` means
+  no revision changes were selected for this batch; an idle tick can still advance
+  past non-revision feed changes without submitting load jobs. `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
@@ -889,6 +1056,9 @@ await managedStore.authorizeDestination({
   destination_ref: destinationRef,
   generation: 1,
   authorized_at: new Date().toISOString(),
+  // The delivery contract this generation serves, recorded once and immutable.
+  pattern: 'file_transfer',
+  transport: 'gcs',
 });
 await managedStore.installBinding(
   reportingManagedDeliveryBindingV1({
@@ -925,6 +1095,56 @@ const reportingDelivery = managed.reportingDeliveryCapabilities;
 await managed.runWorker({ maxIterations: 100 });
 ```
 
+### Pattern and transport on a destination authorization
+
+A destination has exactly one delivery pattern, and a change to its delivery contract mints a new `destination_ref` generation, so the pattern and transport are fixed for an authorization generation. Pass `pattern` (`file_transfer`, `dataset_share`, `warehouse_materialization`) and `transport` (the same lowercase token the offering's `method.transport` uses, such as `gcs` or `s3`) to `authorizeDestination()` when you create the generation. The store records them in `pattern`/`transport` columns and returns them on the authorization that `claimRevocation()` hands to `adapter.revoke()`, so a revocation can be routed to the transport that holds the provider grant instead of being guessed or fanned out.
+
+- Both are optional, and `transport` requires `pattern`. A generation recorded without them stays valid and revocable; it is simply unroutable by transport.
+- They are immutable. Replaying `authorizeDestination()` for the current generation may omit them but cannot state different values, and it cannot add them to a generation recorded without. Change the contract by minting a new generation.
+- `installBinding()` rejects a binding whose `method` or `transport` differs from what its generation recorded, so one generation can never be delivered through one transport and revoked through another.
+- Upgrading: `REPORTING_MANAGED_DELIVERY_MIGRATION` is additive (`ADD COLUMN IF NOT EXISTS`) and safe to re-run. The run that adds the columns backfills each existing generation from the bindings that reference it, but only where every such binding names the same method and the same transport. A generation whose bindings disagree, name no transport, or do not exist is left NULL, and the migration raises a `NOTICE` with how many. Later runs do nothing, so a NULL generation is never re-decided by a binding that arrived afterwards. `managedStore.listDestinationAuthorizationsWithoutContract()` lists the NULL generations with a `reason` (`no_binding`, `binding_without_transport`, `bindings_disagree`, `not_recorded`) so you can see which still need handling.
+
+### Multi-transport delivery with the router
+
+A seller often delivers one feed through several transports: one buyer takes files in a GCS bucket, another in S3. A runtime takes one adapter, so install a router that is itself a `ReportingManagedDeliveryAdapterV1` and dispatches to one adapter per `(pattern, transport)`. The router is pure dispatch with no state of its own, so the store and worker keep every fence they provide today: leases, the authorization-generation check, settlement, the retry and attempt cap, and revocation SLA accounting, per materialization and whichever route served it.
+
+```ts
+import {
+  createReportingManagedDeliveryAdapterRouterV1,
+  createReportingManagedDeliveryRuntime,
+} from '@adcp/sdk/reporting/ledger';
+
+const adapter = createReportingManagedDeliveryAdapterRouterV1({
+  routes: [
+    { id: 'gcs', match: { pattern: 'file_transfer', transport: 'gcs' }, adapter: gcsAdapter },
+    { id: 's3', match: { pattern: 'file_transfer', transport: 's3' }, adapter: s3Adapter },
+  ],
+  // Optional. Only for bindings and authorizations recorded before a transport was.
+  legacyDefault: 'gcs',
+});
+
+const managed = await createReportingManagedDeliveryRuntime({ /* ... */ adapter });
+// or: createPostgresReliableReportingProductionService({ /* ... */ managedDelivery: { adapter, /* ... */ } })
+```
+
+How a route is chosen:
+
+- `deliver()` and `read()` select from the immutable binding alone: `binding.method` (the pattern) and `binding.transport`. They never look at request input, materialization state or the resource.
+- `revoke()` selects from the `pattern` and `transport` recorded on the destination authorization generation (see above). It calls exactly one adapter and never fans out.
+- Anything that cannot be routed throws a typed `ReportingManagedDeliveryRoutingErrorV1` (`code`: `REPORTING_ROUTE_NOT_FOUND`, `REPORTING_ROUTE_TRANSPORT_REQUIRED`, `REPORTING_ROUTE_CONTRACT_UNRECORDED`, `REPORTING_ROUTE_VERIFICATION_UNSUPPORTED`) before any adapter is called. A failed delivery is an ordinary failed attempt and counts toward the attempt cap. A failed revocation is released for retry and counted as overdue once it outlives `authorization_revocation_seconds`, so an unroutable grant is visible, not silent.
+- A binding with no `transport`, and an authorization with no recorded pattern/transport, go to `legacyDefault` if you configured one (and, for a pattern that is stated, only if it is that route's pattern); otherwise they fail as above. A recorded transport with no route never falls back to `legacyDefault`: the router will not guess which provider holds the grant.
+
+Construction throws if route ids repeat, if two routes match the same `(pattern, transport)`, if a route adapter does not declare `revocationFencesDeliveryGenerations: true`, or if a route has an empty `verificationProfiles`. The router's own `verificationProfiles` is the union of its routes' and exists only for compatibility; it never admits a binding.
+
+Admission happens at install and at startup, not at first delivery:
+
+- `createReportingManagedDeliveryRuntime` registers the router's `admitBinding` with the store (`setBindingAdmission`), so `installBinding` refuses a binding whose pattern/transport has no route, or whose `verification_profile` is not one of that route's `verificationProfiles`, before it writes anything. The refusal is the router's own typed error. A runtime whose adapter provides `admitBinding` refuses a store that cannot enforce it. Single adapters define no such hook and behave exactly as before.
+- At runtime construction every advertised managed offering's `method` (pattern and transport) must have a route, and a consumer-receipt offering needs a route that supports `canonical_digest`. Bindings installed before you adopted the router are not re-checked at startup; they fail at delivery with the typed error unless `legacyDefault` takes them.
+
+Optional adapter probe: an adapter may define `probe({ signal })`, which must not mutate provider state. The router probes every route that defines one, concurrently and each within `probeTimeoutMilliseconds` (default 10 seconds; it must be below the runtime's 30 second probe deadline so a hung route is still named), and the runtime calls it before it adopts any durable policy. A failure stops startup with an error naming the failing route id (`Managed Delivery adapter probe failed for route "s3"`); the provider's own message stays on `cause` and out of the message. Offerings are not withdrawn dynamically: fix the route or remove it, then restart.
+
+Observability: when the adapter is a router, `runWorker()` results also carry per-route counts keyed by route id: `deliveriesByRoute`, `deliveryFailuresByRoute`, `revocationsByRoute`, `revocationFailuresByRoute` and `overdueByRoute`. Work no route could take is counted under `UNROUTED_REPORTING_ROUTE_KEY_V1` (`'~unrouted'`, which no route id can equal). The counts carry route ids only, never credentials, locations or provider messages. A single-adapter runtime's result shape is unchanged.
+
 Deployment-wide materialization planning is durably round-robin. The PostgreSQL
 store advances an agent-wide cursor before processing its bounded account page
 and gives every selected account a first-pass share before unused capacity

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,191 @@ 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. A deadline scenario runs a sink with the minimum 1-second load deadline
+  and holds the first load's result past it: the run must reject with the plan
+  and job ID unchanged and that table's persisted deadline grown, the job must
+  end `DONE` without an error (the sink never cancels it), and later runs under
+  the same sink name must converge with no duplicate rows, the same job ID and
+  no second upload. A #3234 scenario runs a sink whose upload of a 50,000-row
+  batch outlasts its 1-second deadline and asserts that it converges within 8
+  runs, loads every row exactly once, never changes the job ID, and never
+  starts an upload after the job exists (a link fast enough to beat the
+  deadline passes and says so).
+- **Cancel probe of the service** (`INFO`, never a failure). It cancels a
+  5000-row load the moment it is created and reports whether BigQuery stopped
+  it; in practice it accepts the cancel and lets the load finish, which is why
+  the sink never cancels a load and finds it by job ID instead.
+- **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.1
+> Generated at: 2026-10-14
+> Library: @adcp/sdk v15.9.1
 > 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: