@adcp/sdk 15.7.1 → 15.8.0

package/docs/guides/CREATIVE-DELIVERY.md

@@ -135,6 +135,12 @@ tool is never reused. Unknown peers receive a legacy projection only when the
 selected product provides one unambiguous ref. Ambiguous or unavailable mappings throw
 `CreativeFormatProjectionError` before transport.
 
+Schema inspection follows local JSON Pointer `$ref` targets, including `$defs`,
+and retains the complete listed document through shared discovery-cache reuse.
+Unused definitions and annotations do not establish support. External references,
+named anchors, and dynamic references are not resolved; inspection never fetches
+schema URLs. Cycles and traversal limits cannot force a guessed wire mode.
+
 Before building creatives, ask the client which mode that write will use:
 
 ```ts
@@ -181,6 +187,16 @@ including polling, deferred, and webhook completions. A creative assigned to
 multiple packages downgrades only when every package resolves to the same
 legacy ref set.
 
+For a canonical seller whose product declares only legacy `format_ids`, those
+authored option refs name IDs minted locally by the SDK. After discovering the
+product with the same client, create/update writes send the equivalent
+`format_kind` + `params` selector and sync writes drop undeclared creative pins.
+Product-cache snapshots retain this seller-origin evidence privately. A selection
+that needs multiple direct selectors, or an undeclared custom format that needs
+its schema identity, fails with `ADCP_CREATIVE_FORMAT_PROJECTION_FAILED` before
+dispatch. Seller-declared option refs remain unchanged. Re-run `getProducts()`
+after restarting before writing selections derived from legacy-only products.
+
 After a process restart, re-run product and media-buy reads that carry enough
 selector context or configure the explicit canonical-to-legacy resolver below.
 An accountless write never consumes a tenant-scoped cached package route based

package/docs/guides/REPORTING-LEDGER-CUTOVER.md

@@ -0,0 +1,405 @@
+# Cutting over to the SDK reporting ledger from your own ledger tables
+
+This guide is for a seller that already runs its own Reliable Reporting ledger
+(tables for configuration generations, obligations and revisions, row files in
+object storage and a warehouse, status issues and transitions) and wants
+`@adcp/sdk` to own the ledger from now on. Read the
+[ledger guide](REPORTING-LEDGER.md) first for the SDK side, and the
+[operations runbook](REPORTING-OPERATIONS.md) for production practice.
+
+The short version:
+
+- Pick **one authoritative ledger per period**. The SDK ledger produces and
+  serves every period from a boundary you choose. Your tables become read-only.
+- **Do not migrate data and do not dual-write.** The old tables keep answering
+  exact reads for old revision IDs until their retention lapses, through a
+  single read-only hook, then you drop them.
+- Everything buyer-visible stays stable across the cutover: old revision IDs
+  keep resolving, and new ones come from the SDK.
+
+## Adopt the SDK tables, or implement the store over your own?
+
+You have two ways to run the SDK's service on top of what you have.
+
+| | Adopt `PostgresReportingLedgerStore` (recommended) | Implement `ReportingLedgerStore` over your tables |
+| --- | --- | --- |
+| Schema | The SDK's `adcp_reporting_*` tables, installed by `REPORTING_LEDGER_MIGRATION` and friends | Yours |
+| Row storage | `rowStorage`: verified chunked rows in your GCS, S3 or Azure bucket, or PostgreSQL | You implement `readRevisionRows` and verify rows against the committed binding yourself |
+| Change feed | `changeFeed: true`: `changesAfter`, current-revision reads, consumer cursors | You implement it, or go without host reads and the warehouse sink |
+| Retention | `maintenance.retention`: period-aligned retirement honouring the change-feed hold | You implement `retireExpiredPeriods` and tombstones, or never retire |
+| Maintenance | `maintenance`: snapshot sweep, abandoned-upload sweep, feed pruning | You write all of it |
+| Warehouse | `@adcp/sdk/reporting/bigquery` sink | Not available: it reads the SDK store |
+| Correctness | Lease fencing, gap-free status checkpoints, immutable generations and the revision binding are enforced in one tested place | Every one of those guarantees is yours to prove |
+| Existing data | Starts empty; old tables stay behind a read-only hook | Old data served natively |
+
+Implementing the store over your own tables is a large surface: the store is
+the correctness boundary for leases, fencing, immutability, snapshot
+checkpoints and the binding digest. You also forgo row storage, the change
+feed, retention and the sink, which are all implemented against the SDK
+tables. Choose it only when a hard constraint forbids a second schema. For
+almost every seller with an existing ledger, adopt the SDK tables and put the
+old ones behind the [legacy fallback](#the-legacy-fallback-hook).
+
+## Core-only setup with GCS object rows
+
+Run the SDK ledger in its own schema or database. The default table set is
+deployment-wide, so the store requires `acknowledgeIsolatedDatabase: true`.
+You do not need the production service: Core plus `maintenance` covers
+production, serving, row storage, the change feed and retention. If you
+advertise Managed Delivery or Reconciled Billing today, read
+[What a Core-only cutover does not carry](#what-a-core-only-cutover-does-not-carry).
+
+```ts
+import { Pool } from 'pg';
+import { Storage } from '@google-cloud/storage';
+import { PostgresReportingLedgerStore } from '@adcp/sdk/reporting/ledger';
+import { createGcsReportingRowObjectProviderV1 } from '@adcp/sdk/reporting/gcs';
+import { createReliableReportingService } from '@adcp/sdk/reporting/service';
+
+// Apply once, in order, with your migration owner (PostgreSQL 13+):
+//   REPORTING_LEDGER_MIGRATION, REPORTING_ROW_STORAGE_MIGRATION,
+//   REPORTING_LEDGER_CHANGES_MIGRATION
+
+const pool = new Pool({ connectionString: process.env.REPORTING_LEDGER_DATABASE_URL });
+const store = new PostgresReportingLedgerStore(pool, {
+  acknowledgeIsolatedDatabase: true,
+  changeFeed: true,
+  rowStorage: {
+    deploymentNamespace: 'prod-us',
+    bindings: {
+      rows: {
+        kind: 'object',
+        provider: 'gcs',
+        location: { bucket: 'acme-reporting' }, // your existing bucket
+        prefix: 'adcp-ledger-rows', // a prefix the legacy writer never uses
+        compression: 'gzip',
+      },
+    },
+    providers: { gcs: createGcsReportingRowObjectProviderV1({ storage: new Storage() }) },
+    selectRowBinding: () => 'rows',
+  },
+});
+await store.readyRowStorage();
+
+const reporting = createReliableReportingService({
+  store,
+  statusRetentionDays: 90, // the commitment advertised to buyers; retention uses it
+  // ...adapters, contact, resolveSource, resolveCurrency, resolveCoverage
+  legacyRevisionReader, // see "The legacy fallback hook"
+  maintenance: {
+    retention: { enabled: true, recordRetentionDays: 120, limit: 100 },
+    changeFeed: { changeRetentionDays: 30, maxFeedHoldDays: 7 },
+  },
+});
+```
+
+With object row storage, PostgreSQL holds only revision headers, row-set and
+chunk manifests (digests, sizes, object keys and versions) and lifecycle
+state. The bytes live in your bucket.
+
+- **Reusing your bucket.** Point the binding at the existing bucket with a
+  prefix the legacy writer never touches. Keys are `{prefix}/{namespace_key}/...`
+  with a hashed account segment, and the SDK only creates, reads and deletes
+  objects under that prefix.
+- **Bucket requirements.** Uniform bucket-level access and enforced public
+  access prevention are required. A lifecycle `Delete` rule that can match live
+  objects under the SDK prefix (no `matchesPrefix`, or an overlapping one) makes
+  the GCS probe refuse the binding, so scope any bucket-wide lifecycle rule to
+  your legacy prefix. Keep retention-driven deletion in the ledger's pruning.
+- **Namespace.** `deploymentNamespace` is mixed into every key. Keep it stable
+  across deploys and distinct per environment.
+- **Maintenance.** `reporting.start({ deploymentWide: true, onError })` runs
+  `maintenance` at most once per `intervalMilliseconds`; or call
+  `reporting.runMaintenance()` from your own scheduler. Retention uses the
+  service's `statusRetentionDays`, so it can never retire a period earlier than
+  the retention you advertise. See
+  [Core-only setup](REPORTING-LEDGER.md#core-only-setup-with-row-storage-change-feed-and-retention).
+  Enable `retention` last.
+
+### Keeping your BigQuery tables fed
+
+`@adcp/sdk/reporting/bigquery` follows the change feed and loads every
+committed revision's verified rows into BigQuery tables you name
+([sink details](REPORTING-LEDGER.md#bigquery-warehouse-sink)). The warehouse
+copy is derived and never served.
+
+```ts
+const sink = createBigQueryReportingWarehouseSinkV1({
+  store,
+  db: pool,
+  bigquery: new BigQuery({ projectId: 'analytics-prod' }),
+  name: 'warehouse',
+  projectId: 'analytics-prod',
+  datasetId: 'reporting',
+  rowsTableId: 'media_buy_delivery_rows_v2', // new tables, not your legacy ones
+  revisionsTableId: 'media_buy_delivery_revisions_v2',
+  mapRow: row => ({ media_buy_id: row.media_buy_id, impressions: row.impressions, spend: row.spend }),
+});
+```
+
+Give the sink its **own new tables** rather than your legacy ones. It adds its
+own fixed columns (`reporting_revision_id`, `reporting_obligation_id`,
+`account_id`, `revision_number`, `finality`, `period_date`, `ordinal`), and
+loading into a table another writer owns invites double counting. Give analysts
+one view that `UNION ALL`s the legacy table, bounded to periods before the
+cutover boundary, with the sink's `current_rows` view, bounded to periods from
+it. Query `current_rows`, never the raw rows table, because pacing snapshots
+are cumulative.
+
+## Cutover, step by step
+
+Choose a **cutover boundary** `B`: the start of a reporting period (for a daily
+schedule, a midnight in the source timezone). Periods that start before `B`
+belong to your legacy ledger forever. Periods that start at or after `B`
+belong to the SDK ledger.
+
+1. **Stand up the SDK ledger without serving it.** Apply the migrations, build
+   the store and service, run `runMaintenance()`, and confirm the GCS probe
+   passes in each environment. Do not call `reporting.install(platform)` yet
+   and do not start its scheduler. Nothing is buyer-visible.
+2. **Wire the legacy fallback hook** (below) over your existing exact-revision
+   read, and exercise it in staging with a revision ID from your legacy tables.
+3. **Rehearse in staging** with a shadow service (see
+   [Shadow comparison](#shadow-comparison)) over a few real periods until row
+   counts, control totals and row digests match.
+4. **Install configurations in the last legacy period.** The SDK plans
+   obligations from `max(schedule.anchor, installedAt)`, rounded up to the next
+   period boundary. Install each active configuration through
+   `installConfiguration` (your `accounts.upsert` mapping) after the start of
+   the last legacy period and before `B`, with `schedule.anchor` no later than
+   `B`. The first period the SDK produces is then `B`, never the period in
+   progress. Verify that no SDK obligation exists for a period before `B`.
+5. **Stop the legacy writer for periods at or after `B`.** The legacy
+   production job must not plan or write any period starting at or after `B`,
+   and must not publish new revisions for earlier ones (see
+   [Corrections to pre-cutover periods](#corrections-to-pre-cutover-periods)).
+   Do this by configuration (disable the planner for the new periods), not by
+   revoking database permissions mid-write.
+6. **Switch the serving path.** Deploy with `reporting.install(platform)` and
+   `reporting.start({ deploymentWide: true, onError })`. From this deploy the
+   SDK's handlers answer `get_reporting_status` and `get_media_buy_delivery`,
+   the capability document is the SDK's, and exact reads for old revision IDs
+   flow through the fallback. Make the legacy tables read-only now (revoke
+   `INSERT`, `UPDATE` and `DELETE` from the application role).
+7. **Watch the first SDK period close:** worker progress, the first revision's
+   binding, a buyer exact read, the warehouse sink's `runOnce()` result, and a
+   legacy-ID exact read through the fallback.
+8. **Decommission** the legacy tables after retention
+   ([below](#decommissioning-the-old-tables)).
+
+Because the boundary is a period boundary, no period is ever produced by both
+ledgers, so no revision ID or `revision_content_sha256` is ever ambiguous.
+
+### What `get_reporting_status` shows after cutover
+
+History starts at the cutover. The SDK ledger knows only the periods it owns,
+from the first boundary at or after each configuration's install instant. A
+status read over a wide range returns the SDK's obligations, revisions and
+health for periods at or after `B` and nothing for earlier periods. Those
+periods are outside the SDK's ownership, so they are absent rather than
+reported as missing history. `HISTORY_UNAVAILABLE` is reserved for periods the
+SDK owns whose obligation records are gone (retired by retention or
+compacted).
+
+Buyers that need pre-cutover data keep using the revision IDs they already
+hold: exact `get_media_buy_delivery` reads for those IDs are served by the
+fallback for as long as your legacy tables retain them. Tell buyers that status
+listing starts at the boundary while exact reads of known revisions continue.
+
+The SDK has no hook for listing pre-cutover periods through
+`get_reporting_status`. Do not synthesize SDK obligations for old periods: that
+is a data migration, with all the identity problems described below.
+
+### Corrections to pre-cutover periods
+
+A late correction to a period that started before `B` needs a decision. The
+SDK cannot produce a revision for a period it never owned, and your legacy
+writer is read-only. Either keep the legacy writer enabled **for corrections of
+pre-cutover periods only**, and keep those tables writable until the last such
+period leaves its correction window, or handle them out of band. The rule that
+must hold is that every period has exactly one authoritative writer.
+
+## The legacy fallback hook
+
+`createReliableReportingService` (and
+`createPostgresReliableReportingProductionService`) takes an optional
+`legacyRevisionReader`. The SDK handler always answers first. Only when the SDK
+ledger has no such revision for the resolved account does it call your reader
+with the same request and context.
+
+```ts
+import type { ReportingLegacyRevisionReaderV1 } from '@adcp/sdk/reporting/ledger';
+
+const legacyRevisionReader: ReportingLegacyRevisionReaderV1 = async (request, context) => {
+  // `context.account` is the framework-resolved account, not request.account.
+  const accountId = (context.account as { id: string }).id;
+  const row = await legacyDb.findRevision({
+    reporting_revision_id: request.reporting_revision_id,
+    account_id: accountId, // scope by the resolved account
+  });
+  if (!row) return null; // not found here either
+  return buildGetMediaBuyDeliveryResponse(row, request.pagination);
+};
+```
+
+The contract:
+
+- **Signature.** `(request, context) => Promise<GetMediaBuyDeliveryResponse | null | undefined>`.
+  The request and context are exactly what the SDK handler received, including
+  `pagination` and `context.signal`.
+- **Not found.** Return `null` or `undefined`. The caller gets the SDK's own
+  nondisclosing `REFERENCE_NOT_FOUND` with `field: "reporting_revision_id"`,
+  identical to an unknown ID on a pure-SDK deployment.
+- **Errors.** An error your reader throws propagates unchanged. Throw
+  `AdcpError('SERVICE_UNAVAILABLE')` for your own outages instead of returning
+  `null`, so buyers retry instead of concluding the revision is gone.
+- **Authorization is yours.** The SDK has resolved the account and cannot judge
+  whether a legacy revision belongs to it. Your reader **must** scope the lookup
+  by `context.account` and return `null` for another account's revision. The SDK
+  also routes a request for an SDK-owned revision that belongs to a *different*
+  account to your reader, so it must never answer for a revision it cannot
+  attribute to the resolved account.
+- **When it is called.** Only for a revision the SDK ledger does not hold for
+  the resolved account.
+- **When it is never called.** For an SDK-owned revision that is expired, whose
+  rows are missing, corrupt or disagree with the committed binding, or that
+  comes with an unusable cursor; and on read capacity exhaustion or any other
+  error. Falling back there could serve different content under an ID the SDK
+  owns.
+- **Read-only and bounded.** The hook must not write to the SDK ledger. The SDK
+  releases its per-account read slot before calling you, so bound your reader's
+  own concurrency and timeouts.
+- **Shape.** Return a full `get_media_buy_delivery` response for that revision,
+  including `reporting_revision_binding` and `reporting_revision` with the
+  revision ID and `revision_content_sha256` your buyers already recorded. Page
+  rows with the same `pagination` contract; your cursors only need to round-trip
+  through your reader.
+- **Identity.** Keep legacy revision IDs distinguishable from SDK IDs (`rrev_`
+  plus a 32-character digest) so a legacy ID can never collide with one the SDK
+  later derives.
+
+## Why not dual-write
+
+A second authoritative ledger looks like a safe migration path and is the most
+dangerous one.
+
+- **Revision IDs and content hashes are buyer-visible.** The SDK derives a
+  revision ID from the obligation and the source publication, and
+  `revision_content_sha256` is the SHA-256 of the canonical JSON of
+  `{ reporting_revision_id, row_count, control_totals, reporting_rows }`. Two
+  ledgers writing the same period produce **two different IDs and two different
+  hashes**, and the buyer's receipts bind to whichever one they saw.
+- **Divergence is silent.** Two writers can disagree on a restatement, an
+  official finality decision or an adjustment, and nothing detects it until a
+  buyer reconciles a bill against a revision the other ledger never recorded.
+- **Immutability is per ledger.** An official revision is terminal in one
+  ledger while the other may still treat the period as open.
+- **Leases and fencing do not span ledgers.** Each fences only its own writers.
+
+A **shadow write for comparison is fine** as long as it is never served: a
+separate database, never installed on the platform, never advertised, never
+notifying. The moment a shadow ledger can answer a buyer, it is a second
+authoritative ledger.
+
+## Shadow comparison
+
+Before the boundary, run the SDK service against a separate shadow database and
+feed it the same source periods. Compare what the two ledgers committed for the
+same period. Do not compare `revision_content_sha256` directly: it includes the
+revision ID, and IDs differ between ledgers by construction. Compare the inputs
+to that hash:
+
+```ts
+import { createHash } from 'node:crypto';
+import { canonicalize } from '@adcp/sdk';
+
+const rowsDigest = (rows: readonly unknown[]) => createHash('sha256').update(canonicalize(rows), 'utf8').digest('hex');
+
+// SDK side, against the shadow store
+const current = await shadowStore.getCurrentRevision({ account_id, reporting_obligation_id });
+const page = await shadowStore.readRevisionRows({
+  reporting_revision_id: current.reporting_revision_id,
+  account_id,
+  offset: 0,
+  limit: Math.max(1, current.binding.rowCount),
+});
+
+// Compare with the legacy revision for the same account and period:
+//   row count, control totals (name and exact decimal value), rowsDigest(rows)
+```
+
+- **Parity means** equal row count, equal `control_totals`, and equal canonical
+  row digests. Array order is part of the canonical form, so sort both sides by
+  your natural key first if your legacy writer does not guarantee order.
+- **Expected differences:** revision ID, `revision_content_sha256`, timestamps,
+  freshness and manifest evidence.
+- Run the comparison until a full set of periods, including one restatement,
+  matches. Then tear the shadow down; do not leave a second ledger running.
+
+## Decommissioning the old tables
+
+After cutover the legacy tables answer exact reads for revision IDs buyers
+already hold. The retention you advertised bounds how long.
+
+1. The last legacy period ends at `B`. Keep its revisions for the legacy
+   deployment's advertised `status_retention_days`, counted from that close.
+2. When that window has lapsed for every legacy period, the fallback has
+   nothing buyers can still legitimately ask for. Remove `legacyRevisionReader`,
+   deploy, and confirm an exact read of an old ID returns `REFERENCE_NOT_FOUND`.
+3. Stop the legacy export jobs, drop the legacy tables, delete or archive the
+   legacy objects (under their own prefix, never under the SDK prefix), and
+   retire the legacy BigQuery tables once analysts have moved to the new view.
+
+Keep the legacy tables for the whole window, not only until the last revision
+was read: buyers verify revisions up to the advertised retention, and that value
+is a commitment. The SDK's `statusRetentionDays` applies to new periods only.
+
+## What a Core-only cutover does not carry
+
+Core-only advertises Reliable Reporting Core: `get_reporting_status` and
+`get_media_buy_delivery`. It does not deliver files to buyer destinations
+(Managed Delivery) and does not accept consumer receipts (Reconciled Billing).
+If your legacy materializations feed buyer-owned destinations, either keep
+delivering them from your own pipeline, reading revisions through
+`listCurrentRevisions` or the change feed rather than from your old tables, or
+adopt the production service with the managed-delivery add-on as a separate,
+later step. Do not advertise a tier the new ledger does not implement.
+
+## Mapping from typical custom tables to the SDK tables
+
+Your names will differ. Map by role.
+
+| Your concept (typical custom table) | SDK table | Notes |
+| --- | --- | --- |
+| Configuration generation (`reporting_core_config_generation`) | `adcp_reporting_configurations` | One immutable generation per `(account_id, delivery_config_id, delivery_config_version)`, with a semantic fingerprint and the frozen source scope and currency in `data` (JSONB). Installed by `installConfiguration`; a changed configuration is a new generation. |
+| Obligation (`reporting_obligation`) | `adcp_reporting_obligations` | One row per configuration and period ordinal: period bounds, `state` (`pending` or `terminal`), `next_attempt_at`, lease owner, generation and expiry. The rest is in `data`. |
+| Revision with explicit columns (`reporting_revision`, 39 columns) | `adcp_reporting_revisions` | Promoted columns are `revision_id`, `obligation_id`, `revision_number`, `finality`, `kind`, `supersedes_revision_id` and `content_sha256`. The remainder (report definition and digest, profile, schema version, row count, control totals, freshness, manifest and finality evidence) is the wire revision inside `data` (JSONB). Do not recreate your 39 columns: use `getCurrentRevision`, `listCurrentRevisions` and the change feed. |
+| Row files (GCS objects plus BigQuery) | `adcp_reporting_row_bindings`, `adcp_reporting_row_sets`, `adcp_reporting_row_chunks`, plus your bucket | Postgres holds the manifest only: digests, sizes, object key and native version per chunk. Rows are verified canonical JSONL chunks in the object store. An unchanged pulse shares its predecessor's row set. BigQuery is fed by the sink, not by the ledger. |
+| Corrections after an official revision | `adcp_reporting_adjustments` | Immutable adjustments bound to the official revision, never superseding revisions. |
+| Status issues | `adcp_reporting_issues` | Obligation-scoped issues with observed and resolved times. |
+| Status transitions and lifecycle | `adcp_reporting_transitions`, `adcp_reporting_lifecycle_state` | Append-only health transitions with a sequence and a durable notified marker, plus a per-obligation reconciliation watermark. Current health is derived from these on read. |
+| Materializations (delivery evidence for buyer destinations) | `adcp_reporting_materializations`, `adcp_reporting_managed_bindings`, `adcp_reporting_receipts` | Managed Delivery add-on only; absent in a Core-only deployment. |
+| Snapshots as status read caches | `adcp_reporting_snapshots`, `adcp_reporting_checkpoints` | Ephemeral cursor state with a 15-minute expiry, swept by maintenance. Not a durable record. |
+| Snapshots as intraday revisions | `adcp_reporting_revisions` with `finality = 'snapshot'` | A pacing snapshot is a revision whose finality is `snapshot`; `official` is terminal. |
+| Retired periods | `adcp_reporting_obligation_tombstones` | A compact record that refuses replays and preserves the audit conclusion after retention deletes a period. |
+| Change log | `adcp_reporting_changes`, `adcp_reporting_feed_consumers` (plus horizons) | With `changeFeed: true`. Replaces polling your revision table. |
+| Row upload bookkeeping | `adcp_reporting_object_write_*` | Intent and fencing records for object uploads. |
+
+## Cutover checklist
+
+- [ ] SDK ledger in an isolated schema or database, migrations applied, probes
+      green in every environment.
+- [ ] Row bucket prefix is separate from legacy objects; no bucket lifecycle rule
+      can delete live SDK objects.
+- [ ] `legacyRevisionReader` scopes by `context.account`, returns `null` for
+      unknown, and throws for its own outages.
+- [ ] Cutover boundary `B` chosen; each configuration installed during the last
+      legacy period; no SDK obligation exists before `B`.
+- [ ] Legacy writer disabled for periods at or after `B` (and a correction path
+      for earlier periods decided).
+- [ ] Legacy tables read-only after the switch deploy.
+- [ ] Buyers told: status listing starts at `B`; old revision IDs keep working
+      until the legacy retention lapses.
+- [ ] Shadow ledger (if any) is unreachable from the serving path.
+- [ ] Decommission date recorded: end of the last legacy period plus the legacy
+      `status_retention_days`.

package/docs/guides/REPORTING-LEDGER.md

@@ -233,6 +233,14 @@ empty revision association. A deployment with per-tenant workers should pass
 the resolved `account_id` to both `planObligations()` and `runWorker()`;
 omitting it intentionally runs a deployment-wide worker.
 
+### Already running your own ledger tables?
+
+Do not dual-write, and do not migrate data. Cut over at a period boundary: the
+SDK ledger produces and serves new periods, and your old tables become
+read-only behind the optional `legacyRevisionReader`, which answers exact
+`get_media_buy_delivery` reads only for revisions the SDK ledger does not hold.
+See [Cutting over to the SDK reporting ledger](REPORTING-LEDGER-CUTOVER.md).
+
 ### Migrating an existing manual lifecycle
 
 Keep the same `PostgresReportingLedgerStore` and run the same
@@ -373,6 +381,22 @@ await store.readyRowStorage();
   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
+  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
+  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
+  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
+  that referenced it, so it is not leaked.
 - An upload runs only while the obligation lease still covers
   `writeDeadlineMilliseconds` plus five seconds. A fenced write intent records
   every object the upload created, and the ledger commit closes the intent in
@@ -546,6 +570,111 @@ because the retired obligations no longer exist.
 always sweeps abandoned row uploads and expired cursor snapshots and
 checkpoints, and retires periods when retention is enabled.
 
+### Compacting superseded snapshots (opt-in)
+
+> **Do not enable this in production before the next eligible AdCP minor after
+> November 20, 2026.** Until then the published protocol still describes
+> superseded snapshots as preserved. The option is off by default, and
+> retaining the whole chain, as the ledger does by default, stays conformant.
+
+[adcontextprotocol/adcp#8100](https://github.com/adcontextprotocol/adcp/pull/8100)
+separates the two things `status_retention_days` covers. **Metadata** for every
+revision stays queryable for the whole window. **Content** (the rows) is owed
+only for the revisions a buyer is likely to read, so a seller that publishes a
+snapshot every 15 minutes need not keep thousands of full snapshots per period.
+
+The window runs from the revision's `created_at`. Once a later revision names it
+in `supersedes_reporting_revision_id`, it runs from that successor's
+`created_at` instead. Within its window the seller must keep content readable
+by exact read when the revision is:
+
+- (a) the current, unsuperseded revision of its slice, which includes every
+  official revision;
+- (b) the revision the current revision supersedes;
+- (c) a superseded snapshot inside its recovery grace, `max(automated recovery
+  window, one hour)` after its successor's `created_at`;
+- (d) named, for the requesting caller, by that caller's own reporting receipt
+  in any status, or by its current consumer status statement with status
+  `received`, `unreadable` or `content_mismatch`.
+
+Any other superseded snapshot may be compacted to metadata only. An exact read
+of a compacted revision returns the same nondisclosing `REFERENCE_NOT_FOUND` as
+an unknown ID. A revision in (a) to (d) whose content cannot be served is
+`SERVICE_UNAVAILABLE` (`REVISION_UNREADABLE`), never not-found.
+
+```ts
+// Core-only service
+createReliableReportingService({
+  // ...
+  maintenance: { compaction: { enabled: true, limit: 100 } },
+});
+
+// Production service
+await createPostgresReliableReportingProductionService({
+  // ...
+  compaction: { enabled: true, limit: 100 },
+});
+
+// Or call the store directly
+await store.compactSupersededSnapshots({
+  statusRetentionDays: 30,
+  automatedRecoveryWindowSeconds: 3600,
+  limit: 100,
+});
+```
+
+Both options take `{ enabled: true; limit?: number }` (default `limit` 100 per
+pass) and reuse the service's `statusRetentionDays` and
+`automatedRecoveryWindowSeconds`. The maintenance task is named
+`snapshot compaction`.
+
+A snapshot is compacted only when all of these hold:
+
+- A later revision supersedes it, and it is not the revision the current
+  revision supersedes. Current and official revisions are never compacted.
+- Its recovery grace has passed: `max(automatedRecoveryWindowSeconds, 3600)`
+  seconds since its successor's `created_at`.
+- No caller is owed it. The check spans every caller: a receipt in any status
+  (current or superseded), or a current `received`, `unreadable` or
+  `content_mismatch` consumer status statement, from any caller keeps the
+  revision while its window (`statusRetentionDays` from its successor's
+  `created_at`) is open. After that window nothing is owed any more.
+- The obligation holds no live worker lease, no Managed Delivery
+  materialization of that revision is still `pending`, and no live change-feed
+  consumer (updated within `maxFeedHoldDays`) has yet to pass that revision's
+  change row. This is the same hold retirement applies, narrowed to the
+  revision.
+- It has rows. A revision with no rows has nothing to reclaim.
+
+Compaction drops row content only. The revision header, its manifest and every
+metadata listing stay, and `listRevisionMetadata` and the status views keep
+listing it. `listRevisions`, which hydrates rows, omits compacted revisions.
+The `revision` view of `get_reporting_status` for a compacted revision answers
+as an unavailable lookup, like an exact read.
+
+It uses the same three resumable phases as retirement. Under the account lock it
+re-checks eligibility and marks the row set `pruning` (reads answer as expired;
+no new revision can share its chunks). It then deletes external objects at their
+recorded versions through the fenced delete path, skipping any object a row set
+that is not being pruned still references. Finally it deletes the chunk
+manifest and any PostgreSQL chunk body nothing else uses, and marks the row set
+`pruned`. A crash after the first phase leaves a `pruning` row set that the next
+pass finishes. Chunks shared by byte-identical revisions survive until the last
+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.
+
 ### Core-only setup with row storage, change feed and retention
 
 You do not need the production service (managed delivery, notifications and
@@ -611,6 +740,7 @@ Tasks, in order:
 | `row upload sweep`    | always                                            | Resolves abandoned object uploads (100 per pass); no-op without row storage. |
 | `change-feed pruning` | when `maintenance.changeFeed` is set              | `pruneChanges` with `changeRetentionDays` and `maxFeedHoldDays`.     |
 | `retention`           | when `maintenance.retention.enabled` is `true`    | `retireExpiredPeriods` with the service's `statusRetentionDays` and the feed's `maxFeedHoldDays`. |
+| `snapshot compaction` | when `maintenance.compaction.enabled` is `true`   | `compactSupersededSnapshots` with the service's `statusRetentionDays` and `automatedRecoveryWindowSeconds` (see [Compacting superseded snapshots](#compacting-superseded-snapshots-opt-in)). |
 
 Notes:
 

package/docs/guides/REPORTING-OPERATIONS.md

@@ -120,6 +120,15 @@ service runs for you. See
    `status_retention_days` is the window you intend to keep. Retirement deletes
    rows and ledger records for whole periods and cannot be undone. Keep backups
    for any longer audit requirement.
+7. **Snapshot compaction (optional).** Off by default; enable `compaction`
+   (`maintenance.compaction` on the Core-only service) only to reclaim the
+   content of superseded snapshots. Do not enable it in production before the
+   next eligible AdCP minor after November 20, 2026, when the protocol takes
+   compaction into effect. Roll it out after retention, with a small `limit`,
+   and watch the `snapshot compaction` task's `failed` IDs. See
+   [Compacting superseded snapshots](REPORTING-LEDGER.md#compacting-superseded-snapshots-opt-in)
+   for the rule and what it keeps. Compaction cannot be undone; backups hold
+   any longer evidence.
 
 Alert on these row-storage signals:
 
@@ -127,6 +136,9 @@ Alert on these row-storage signals:
   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.
+- 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.

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
-> Generated at: 2026-10-10
-> Library: @adcp/sdk v15.7.1
+> Generated at: 2026-10-11
+> Library: @adcp/sdk v15.8.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.
@@ -2140,6 +2140,7 @@ These docs are available locally in the repo and hosted at https://adcontextprot
 | Conformance (property-based fuzzing) | docs/guides/CONFORMANCE.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/CONFORMANCE.md) |
 | Reporting source executor (seller adapters) | docs/guides/REPORTING-SOURCE-EXECUTOR.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/REPORTING-SOURCE-EXECUTOR.md) |
 | Seller reporting ledger | docs/guides/REPORTING-LEDGER.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/REPORTING-LEDGER.md) |
+| Reporting ledger cutover from custom tables | docs/guides/REPORTING-LEDGER-CUTOVER.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/REPORTING-LEDGER-CUTOVER.md) |
 | Buyer reporting reconciliation | docs/guides/REPORTING-RECONCILIATION.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/REPORTING-RECONCILIATION.md) |
 | Reliable Reporting production operations | docs/guides/REPORTING-OPERATIONS.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/REPORTING-OPERATIONS.md) |
 | Validate your agent (5-command checklist) | docs/guides/VALIDATE-YOUR-AGENT.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/VALIDATE-YOUR-AGENT.md) |

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

@@ -11,8 +11,8 @@ below as the publication/deployment gate.
 
 | Fact | Value |
 | --- | --- |
-| Exact npm package | `@adcp/sdk@15.7.1` |
-| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@15.7.1 dist.integrity` |
+| Exact npm package | `@adcp/sdk@15.8.0` |
+| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@15.8.0 dist.integrity` |
 | Node.js runtime | `^20.19.0 || >=22.12.0` |
 | Default AdCP wire release | `3.2.3` |
 | Maintained wire releases | `v2.5`, `v2.6`, `v3`, `3.0.0`, `3.0`, `3.0.1`, `3.0.2`, `3.0.3`, `3.0.4`, `3.0.5`, `3.0.6`, `3.0.7`, `3.0.8`, `3.0.9`, `3.0.10`, `3.0.11`, `3.0.12`, `3.0.13`, `3.0.14`, `3.0.15`, `3.0.16`, `3.0.17`, `3.0.18`, `3.0.19`, `3.0.20`, `3.0.21`, `3.0.22`, `3.0.23`, `3.0.24`, `3.0.25`, `3.1.0`, `3.1`, `3.1.1`, `3.1.2`, `3.1.3`, `3.1.4`, `3.1.5`, `3.1.6`, `3.1.7`, `3.1.8`, `3.1.9`, `3.1.10`, `3.1.11`, `3.1.12`, `3.1.13`, `3.1.14`, `3.1.15`, `3.1.16`, `3.1.17`, `3.1.18`, `3.1.19`, `3.1.20`, `3.1.21`, `3.1.22`, `3.1.23`, `3.1.24`, `3.2.1`, `3.2`, `3.2.2`, `3.2.3` |
@@ -21,8 +21,8 @@ below as the publication/deployment gate.
 Install exact production inputs rather than a moving range or dist-tag:
 
 ```bash
-npm install --save-exact '@adcp/sdk@15.7.1'
-npm view '@adcp/sdk@15.7.1' dist.integrity
+npm install --save-exact '@adcp/sdk@15.8.0'
+npm view '@adcp/sdk@15.8.0' dist.integrity
 ```
 
 ### Required and optional peers