@adcp/sdk 15.7.0 → 15.8.0

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-09
-> Library: @adcp/sdk v15.7.0
+> 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.0` |
-| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@15.7.0 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.0'
-npm view '@adcp/sdk@15.7.0' dist.integrity
+npm install --save-exact '@adcp/sdk@15.8.0'
+npm view '@adcp/sdk@15.8.0' dist.integrity
 ```
 
 ### Required and optional peers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "15.7.0",
+  "version": "15.8.0",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",