@adcp/sdk 15.8.1 → 16.0.0-beta.1

package/docs/guides/REPORTING-LEDGER.md

@@ -2,6 +2,8 @@
 
 `@adcp/sdk/reporting/ledger` turns a conforming reporting source into durable seller-side Reliable Reporting Core. It is separate from the buyer-side `reconcileReporting` API.
 
+> **Stability:** the storage, row, change-feed, managed-delivery and warehouse-sink exports (`@adcp/sdk/reporting/gcs`, `s3`, `azure`, `bigquery`, and the `@experimental` exports of `ledger`) are experimental and may change in minor releases. Pin with `~`. See the [Reliable Reporting stability policy](REPORTING-STABILITY.md).
+
 ## Recommended: install the lifecycle service
 
 `createReliableReportingService` is the adapter-first Core path. A
@@ -338,6 +340,19 @@ do {
 Removing rows from ledger documents frees space only after `VACUUM FULL` or an
 online repack of `adcp_reporting_revisions` and `adcp_reporting_adjustments`.
 
+### Stored field names
+
+Stored values use AdCP's names and bounds: a chunk's `object_ref` and
+`native_version_ref` (1 to 1024 characters each, enforced by `CHECK`
+constraints), `size_bytes` (the stored object's size after compression, as in
+the AdCP file manifest), and `canonical_size_bytes` (the uncompressed canonical
+bytes that the chunk digests cover; a row set's `content_size_bytes` is the
+byte count of the content its `content_sha256` covers). A row set records `format` (`jsonl`) and
+`algorithm` (`adcp_jcs_rows_v1`). Neither token feeds a digest. Installed
+databases upgrade in place when you re-apply `REPORTING_ROW_STORAGE_MIGRATION`;
+see [Breaking: reporting row storage field alignment](../migration-reporting-row-storage-alignment.md)
+for the old names, the API renames and the re-sync option.
+
 ### Object storage bindings
 
 Rows can live in object storage instead of PostgreSQL. A binding is defined in
@@ -368,7 +383,7 @@ const store = new PostgresReportingLedgerStore(pool, {
     providers: {
       filesystem: createFilesystemReportingRowObjectProviderV1({ roots: { reports: '/var/lib/adcp/rows' } }),
     },
-    selectRowBinding: ({ canonical_byte_count }) => (canonical_byte_count < 256 * 1024 ? 'inline' : 'reports'),
+    selectRowBinding: ({ content_size_bytes }) => (content_size_bytes < 256 * 1024 ? 'inline' : 'reports'),
   },
 });
 await store.readyRowStorage();
@@ -380,19 +395,41 @@ await store.readyRowStorage();
 - Keys always start with `{prefix}/{namespace_key}/` and use a hashed account
   segment, never a raw account ID. Override `keyTemplate` with the placeholders
   in `REPORTING_ROW_KEY_PLACEHOLDERS`; templates must include
-  `{content_sha256}` and `{chunk_index}`.
-  Enabling snapshot compaction additionally requires `{revision_key}` (see
-  [Compacting superseded snapshots](#compacting-superseded-snapshots-opt-in)).
-- A custom `keyTemplate` without `{account_key}` and `{revision_key}` can map
-  row sets from different obligations or accounts with identical chunk content
-  (an adjustment's digest covers its rows alone) to one object, which the
-  second writer adopts. Every delete path (period retirement, compaction and
-  the intent sweep) therefore skips an object while a live row set outside the
+  `{content_sha256}`, `{chunk_index}` and `{revision_key}`. `{revision_key}` is
+  required on every writable binding, so each row set writes its own object
+  keys (it hashes the row-set ID, so two uploads never name the same key). The store refuses a
+  template without it when it is configured and again in `readyRowStorage`,
+  with `INVALID_INPUT`.
+  `{period_date}` renders AdCP's `YYYY-MM-DD`: the calendar date of the period
+  start in the period's `source_timezone`, never UTC (a period starting
+  `2026-10-02T07:00:00Z` in `America/Los_Angeles` is `2026-10-02`; one starting
+  `2026-10-01T15:00:00Z` in `Asia/Tokyo` is also `2026-10-02`). It is one path
+  segment, so the default layout is
+  `{prefix}/{namespace_key}/{account_key}/2026-10-02/{finality}/...`, not
+  `2026/10/02/`. A missing, unknown or non-IANA timezone fails the write with
+  `INVALID_INPUT` rather than guessing a date. The rendered key must stay within
+  AdCP's 1024-character `object_ref` bound.
+- Rows written under an older template without `{revision_key}` stay readable:
+  every read uses the chunk's recorded `object_ref`, never a re-rendered key.
+  Changing a template needs a new binding ID, and the old definition must stay
+  configured while revisions reference it. Mark that old definition
+  `readOnly: true` to keep it configured without `{revision_key}`: it is
+  exempt from the requirement, never selected for new writes, and still used
+  for reads and retirement. A read-only binding is still registered and
+  probed by `readyRowStorage`, so keep its location reachable (and keep
+  enforcing `readOnly` in every process that shares the database: it is not
+  stored).
+- Header-only revisions share their predecessor's chunks within an obligation,
+  and chunk rows written under an older template can name one object from
+  several row sets. Every delete path (period retirement, compaction and the
+  intent sweep) therefore skips an object while a live row set outside the
   operation still references the same binding, key and native version, or an
-  open write intent created it. The reference check and the delete run in one
+  open write intent created it. (With unique keys, a create-only write only
+  finds an existing object when a writer retries the same row set.) The check
+  and delete run under the per-object lock described below. The reference check and the delete run in one
   transaction under a per-object advisory lock, and a commit that adopts an
-  existing object takes the same lock, re-reads the object and holds the lock
-  until its chunk rows commit. A delete that wins the lock makes the adopting
+  existing object takes the same lock, proves the object is still there and
+  holds the lock until its chunk rows commit. A delete that wins the lock makes the adopting
   commit fail with `STATE_UNAVAILABLE` (the writer re-uploads once its intent
   lapses); a commit that wins is seen by the delete, which skips. A skipped
   object is deleted by the retirement, compaction or sweep of the last row set
@@ -415,7 +452,16 @@ await store.readyRowStorage();
   filesystem is wrong, not the code.
 - Custom providers implement `ReportingRowObjectProviderV1`. Run
   `runReportingRowObjectProviderConformanceV1(provider, { location, prefix })`
-  against a dedicated test prefix before using one.
+  against a dedicated test prefix before using one. Provider calls take and
+  return AdCP's names: `objectRef` (the decoded, destination-relative object
+  key) and `nativeVersionRef` (the decoded provider-native version), each 1 to
+  1024 characters. Implement the optional `stat({ objectRef, nativeVersionRef })`,
+  which returns `{ sizeBytes }` for that exact version or `null` when it is
+  absent, without reading the body. The commit transaction uses it to prove an
+  adopted object is unchanged (native versions are write-unique, so the same
+  version at the recorded size is the same bytes) instead of downloading it
+  while holding the account and object locks. A provider without `stat` falls
+  back to reading the whole object there. All bundled providers implement it.
 
 #### Cloud providers
 
@@ -565,6 +611,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
@@ -665,15 +736,16 @@ revision referencing them is compacted.
 Compaction records no change-feed row: the revision's metadata did not change,
 and a sink still catching up holds the revision back (above).
 
-Compaction requires every object row binding's `keyTemplate` to include
-`{revision_key}` (the default template does). Deletes now skip objects another
-row set still references (see [Object storage](#object-storage-bindings)),
-so this is defense in depth rather than the only guard: with `{revision_key}`
-no two revisions ever name the same object, so compaction never depends on the
-reference check. The SDK fails closed: `createReliableReportingService` and
-`createPostgresReliableReportingProductionService` throw at construction when
-compaction is enabled and a binding's template omits `{revision_key}`, and
-`compactSupersededSnapshots` throws the same error before deleting anything.
+Every writable object row binding's `keyTemplate` must include
+`{revision_key}` (the default template does), so two uploads never name the
+same object. Deletes skip objects another row set still references (see
+[Object storage](#object-storage-bindings)), which still matters for header-only
+revisions that share chunks within an obligation and for rows written under an
+older template, so compaction does not depend on key uniqueness alone. A
+`readOnly` binding for older rows is exempt: it never takes commits, so nothing
+can adopt through it. The SDK fails closed when the store is configured, and
+`createReliableReportingService`, `createPostgresReliableReportingProductionService`
+and `compactSupersededSnapshots` re-check before compacting.
 
 ### Core-only setup with row storage, change feed and retention
 
@@ -791,11 +863,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 +931,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,24 +943,135 @@ 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
   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.
+  `revision_number`, `finality`, `period_date` and `ordinal` to your mapped
+  columns. `period_date` is a `DATE`: the calendar date of the period start in
+  the period's `source_timezone`, as `YYYY-MM-DD` (an SDK column derived from
+  AdCP's `period`), not the UTC date unless that is the source timezone. A
+  period starting `2026-10-02T07:00:00Z` in `America/Los_Angeles` is
+  `2026-10-02`; one starting `2026-10-01T15:00:00Z` in `Asia/Tokyo` is also
+  `2026-10-02`. It is the start's date only, not a coverage range: a period
+  that crosses local midnight or spans several days is one `period_date`, so
+  `PARTITION BY period_date` holds source-local days and a UTC "yesterday"
+  filter can straddle partitions. The sink computes it with the same helper
+  that renders `{period_date}` in object keys. It fails the batch rather than
+  load a guessed date when a revision's period or timezone is missing or
+  invalid. The batch stays retained, so the sink stops until that revision's
+  period is repaired (or the runtime's timezone data is upgraded); reset with
+  `discardRetainedPlan` restarts from the beginning, so empty the tables first.
 - 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 +1080,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 +1116,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 +1155,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