@adcp/sdk 15.7.1 → 15.8.0

package/dist/lib/reporting/ledger/types.d.ts

@@ -1009,6 +1009,32 @@ export interface ReportingProducerV1 {
 export type ReportingSourceWithReaderV1 = ReportingSourceExecutorV1 & ReportingSourceStagedObjectReaderV1;
 export type ReportingStatusHandlerV1 = (request: AdcpToolMap['get_reporting_status']['params'], context: HandlerContext<unknown>) => Promise<GetReportingStatusResponse>;
 export type ReportingDeliveryHandlerV1 = (request: AdcpToolMap['get_media_buy_delivery']['params'], context: HandlerContext<unknown>) => Promise<AdcpToolMap['get_media_buy_delivery']['result']>;
+/**
+ * Exact-revision reader for revisions the SDK ledger does not own, typically a
+ * seller's pre-cutover ledger tables. It receives the same request and context
+ * as `get_media_buy_delivery` and returns the protocol response, or
+ * `null`/`undefined` when it has no such revision.
+ *
+ * Authorization is the reader's responsibility. The SDK has already resolved
+ * the account (`context.account`) and cannot tell whether a legacy revision
+ * belongs to it, so the reader MUST scope the lookup by that account and return
+ * `null` for a revision that belongs to another one. Never return a response
+ * for a revision the resolved account cannot read.
+ */
+export type ReportingLegacyRevisionReaderV1 = (request: AdcpToolMap['get_media_buy_delivery']['params'], context: HandlerContext<unknown>) => Promise<AdcpToolMap['get_media_buy_delivery']['result'] | null | undefined>;
+export interface CreateReportingDeliveryHandlerOptionsV1 {
+    /**
+     * Consulted only when the SDK ledger has no such revision for the resolved
+     * account (unknown id, or an id owned by a different account). Never
+     * consulted for an SDK-owned revision that is expired, has unavailable or
+     * corrupt rows, or carries an unusable cursor, nor for capacity or other
+     * errors: falling back there could serve different content under an id the
+     * SDK owns. A `null`/`undefined` result is the same nondisclosing
+     * `REFERENCE_NOT_FOUND` the SDK returns itself; an error the reader throws
+     * propagates unchanged.
+     */
+    legacyRevisionReader?: ReportingLegacyRevisionReaderV1;
+}
 export interface CreateReportingProducerOptionsV1 {
     store: ReportingLedgerStore;
     source: ReportingSourceWithReaderV1;

package/dist/lib/reporting/service/index.d.mts

@@ -4,9 +4,9 @@ import type { DecisioningPlatform } from '../../server/decisioning/platform.mjs'
 import type { ReliableReportingPlatform } from '../../server/decisioning/specialisms/reporting.mjs';
 import type { ReportingDeliveryCapabilities, ReportingDeliveryOffering } from '../../types/tools.generated.mjs';
 import { type CreatePostgresPersistentNotificationRuntimeOptions, type PostgresPersistentNotificationRuntime } from '../../server/notification-subscriptions/index.mjs';
-import { REPORTING_LEDGER_MIGRATION, PostgresReportingLedgerStore, PostgresReportingManagedDeliveryStore, type CreateReportingProducerOptionsV1, type ReportingConsumerMismatchEscalationV1, type ReportingLedgerConfigurationV1, type ReportingLedgerStore, type ReportingProducerContactV1, type ReportingProducerV1, type ReportingManagedDeliveryAdapterV1, type ReportingManagedDeliveryRuntimeV1, type PostgresReportingManagedDeliveryStoreOptions, type PostgresReportingNotificationActivityOptions, type PostgresReportingNotificationActivityRuntime, type ReportingPgPool, type ReportingRowStorageOptionsV1, type ReportingSourceWithReaderV1 } from '../ledger/index.mjs';
+import { REPORTING_LEDGER_MIGRATION, PostgresReportingLedgerStore, PostgresReportingManagedDeliveryStore, type CreateReportingProducerOptionsV1, type ReportingConsumerMismatchEscalationV1, type ReportingLedgerConfigurationV1, type ReportingLedgerStore, type ReportingLegacyRevisionReaderV1, type ReportingProducerContactV1, type ReportingProducerV1, type ReportingManagedDeliveryAdapterV1, type ReportingManagedDeliveryRuntimeV1, type PostgresReportingManagedDeliveryStoreOptions, type PostgresReportingNotificationActivityOptions, type PostgresReportingNotificationActivityRuntime, type ReportingPgPool, type ReportingRowStorageOptionsV1, type ReportingSourceWithReaderV1 } from '../ledger/index.mjs';
 import { type PostgresReportingWebhookActivityV1 } from '../webhook-activity.mjs';
-import { type ReportingChangeFeedMaintenanceOptionsV1, type ReportingLedgerMaintenanceTaskResultV1, type ReportingRetentionOptionsV1 } from './maintenance.mjs';
+import { type ReportingChangeFeedMaintenanceOptionsV1, type ReportingLedgerMaintenanceTaskResultV1, type ReportingCompactionOptionsV1, type ReportingRetentionOptionsV1 } from './maintenance.mjs';
 import type { InlineReportingReplayRetentionV1 } from '../source/index.mjs';
 import { type InlineReportingDeliveryFetchV1, type ReportingSourceOfferingV1 } from '../source/index.mjs';
 /** The intentionally small provider boundary: one bounded slice fetch plus immutable metadata. */
@@ -165,12 +165,30 @@ export interface CreateReliableReportingServiceOptionsV1<TCtxMeta = Record<strin
      * store to be built with `changeFeed: true`.
      */
     maintenance?: ReliableReportingMaintenanceOptionsV1;
+    /**
+     * Serve exact revision reads (`get_media_buy_delivery`) for revisions this
+     * ledger does not hold, such as a seller's pre-cutover ledger tables. The
+     * SDK ledger answers first; the reader is called with the same request and
+     * context only when the SDK has no such revision for the resolved account.
+     * It is never called for an SDK-owned revision that is expired or has
+     * unavailable or corrupt rows, nor on capacity or other errors. A
+     * `null`/`undefined` result becomes the SDK's own nondisclosing
+     * `REFERENCE_NOT_FOUND`.
+     *
+     * The reader owns authorization: it MUST scope its lookup by
+     * `context.account` and return `null` for another account's revision. Read
+     * only; never write to the SDK ledger from it. See
+     * `docs/guides/REPORTING-LEDGER-CUTOVER.md`.
+     */
+    legacyRevisionReader?: ReportingLegacyRevisionReaderV1;
 }
 export interface ReliableReportingMaintenanceOptionsV1 {
     /** Minimum time between scheduled maintenance passes. Defaults to 300000 (5 minutes). */
     intervalMilliseconds?: number;
     /** Period-aligned retention; see the production service's `retention`. */
     retention?: ReportingRetentionOptionsV1;
+    /** Opt-in snapshot compaction; see the production service's `compaction`. */
+    compaction?: ReportingCompactionOptionsV1;
     /** Change-feed pruning and consumer hold; see the production service's `changeFeed`. */
     changeFeed?: ReportingChangeFeedMaintenanceOptionsV1;
 }
@@ -244,6 +262,18 @@ export type CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta =
      * within `changeFeed.maxFeedHoldDays`, default 7) has read its changes.
      */
     retention?: ReportingRetentionOptionsV1;
+    /**
+     * Opt in to compacting superseded snapshot revisions to metadata only, as
+     * adcontextprotocol/adcp#8100 permits. Off by default. Each scheduler pass
+     * drops the row content of snapshots that are superseded, past their
+     * recovery grace and not owed to any caller (receipts, current
+     * `received` / `unreadable` / `content_mismatch` statements), while every
+     * revision's metadata stays. Official revisions are never compacted. Uses
+     * this service's `statusRetentionDays` and `automatedRecoveryWindowSeconds`.
+     * The protocol takes compaction into effect only in the next eligible minor
+     * after November 20, 2026: do not enable this in production before then.
+     */
+    compaction?: ReportingCompactionOptionsV1;
     /**
      * Maintain the host change feed (`changesAfter`, `getCurrentRevision`,
      * `listCurrentRevisions` on `stores.core`). Adds
@@ -329,4 +359,4 @@ export interface PostgresReliableReportingProductionServiceV1<TCtxMeta = Record<
  */
 export declare function createPostgresReliableReportingProductionService<TCtxMeta = Record<string, unknown>>(options: CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta>): Promise<PostgresReliableReportingProductionServiceV1<TCtxMeta>>;
 export * from './conformance.mjs';
-export { ReportingMaintenancePartialFailureError, type ReportingChangeFeedMaintenanceOptionsV1, type ReportingLedgerMaintenanceStoreV1, type ReportingLedgerMaintenanceTaskNameV1, type ReportingLedgerMaintenanceTaskResultV1, type ReportingRetentionOptionsV1, } from './maintenance.mjs';
+export { ReportingMaintenancePartialFailureError, type ReportingChangeFeedMaintenanceOptionsV1, type ReportingCompactionOptionsV1, type ReportingLedgerMaintenanceStoreV1, type ReportingLedgerMaintenanceTaskNameV1, type ReportingLedgerMaintenanceTaskResultV1, type ReportingRetentionOptionsV1, } from './maintenance.mjs';

package/dist/lib/reporting/service/index.d.ts

@@ -4,9 +4,9 @@ import type { DecisioningPlatform } from '../../server/decisioning/platform';
 import type { ReliableReportingPlatform } from '../../server/decisioning/specialisms/reporting';
 import type { ReportingDeliveryCapabilities, ReportingDeliveryOffering } from '../../types/tools.generated';
 import { type CreatePostgresPersistentNotificationRuntimeOptions, type PostgresPersistentNotificationRuntime } from '../../server/notification-subscriptions';
-import { REPORTING_LEDGER_MIGRATION, PostgresReportingLedgerStore, PostgresReportingManagedDeliveryStore, type CreateReportingProducerOptionsV1, type ReportingConsumerMismatchEscalationV1, type ReportingLedgerConfigurationV1, type ReportingLedgerStore, type ReportingProducerContactV1, type ReportingProducerV1, type ReportingManagedDeliveryAdapterV1, type ReportingManagedDeliveryRuntimeV1, type PostgresReportingManagedDeliveryStoreOptions, type PostgresReportingNotificationActivityOptions, type PostgresReportingNotificationActivityRuntime, type ReportingPgPool, type ReportingRowStorageOptionsV1, type ReportingSourceWithReaderV1 } from '../ledger';
+import { REPORTING_LEDGER_MIGRATION, PostgresReportingLedgerStore, PostgresReportingManagedDeliveryStore, type CreateReportingProducerOptionsV1, type ReportingConsumerMismatchEscalationV1, type ReportingLedgerConfigurationV1, type ReportingLedgerStore, type ReportingLegacyRevisionReaderV1, type ReportingProducerContactV1, type ReportingProducerV1, type ReportingManagedDeliveryAdapterV1, type ReportingManagedDeliveryRuntimeV1, type PostgresReportingManagedDeliveryStoreOptions, type PostgresReportingNotificationActivityOptions, type PostgresReportingNotificationActivityRuntime, type ReportingPgPool, type ReportingRowStorageOptionsV1, type ReportingSourceWithReaderV1 } from '../ledger';
 import { type PostgresReportingWebhookActivityV1 } from '../webhook-activity';
-import { type ReportingChangeFeedMaintenanceOptionsV1, type ReportingLedgerMaintenanceTaskResultV1, type ReportingRetentionOptionsV1 } from './maintenance';
+import { type ReportingChangeFeedMaintenanceOptionsV1, type ReportingLedgerMaintenanceTaskResultV1, type ReportingCompactionOptionsV1, type ReportingRetentionOptionsV1 } from './maintenance';
 import type { InlineReportingReplayRetentionV1 } from '../source';
 import { type InlineReportingDeliveryFetchV1, type ReportingSourceOfferingV1 } from '../source';
 /** The intentionally small provider boundary: one bounded slice fetch plus immutable metadata. */
@@ -165,12 +165,30 @@ export interface CreateReliableReportingServiceOptionsV1<TCtxMeta = Record<strin
      * store to be built with `changeFeed: true`.
      */
     maintenance?: ReliableReportingMaintenanceOptionsV1;
+    /**
+     * Serve exact revision reads (`get_media_buy_delivery`) for revisions this
+     * ledger does not hold, such as a seller's pre-cutover ledger tables. The
+     * SDK ledger answers first; the reader is called with the same request and
+     * context only when the SDK has no such revision for the resolved account.
+     * It is never called for an SDK-owned revision that is expired or has
+     * unavailable or corrupt rows, nor on capacity or other errors. A
+     * `null`/`undefined` result becomes the SDK's own nondisclosing
+     * `REFERENCE_NOT_FOUND`.
+     *
+     * The reader owns authorization: it MUST scope its lookup by
+     * `context.account` and return `null` for another account's revision. Read
+     * only; never write to the SDK ledger from it. See
+     * `docs/guides/REPORTING-LEDGER-CUTOVER.md`.
+     */
+    legacyRevisionReader?: ReportingLegacyRevisionReaderV1;
 }
 export interface ReliableReportingMaintenanceOptionsV1 {
     /** Minimum time between scheduled maintenance passes. Defaults to 300000 (5 minutes). */
     intervalMilliseconds?: number;
     /** Period-aligned retention; see the production service's `retention`. */
     retention?: ReportingRetentionOptionsV1;
+    /** Opt-in snapshot compaction; see the production service's `compaction`. */
+    compaction?: ReportingCompactionOptionsV1;
     /** Change-feed pruning and consumer hold; see the production service's `changeFeed`. */
     changeFeed?: ReportingChangeFeedMaintenanceOptionsV1;
 }
@@ -244,6 +262,18 @@ export type CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta =
      * within `changeFeed.maxFeedHoldDays`, default 7) has read its changes.
      */
     retention?: ReportingRetentionOptionsV1;
+    /**
+     * Opt in to compacting superseded snapshot revisions to metadata only, as
+     * adcontextprotocol/adcp#8100 permits. Off by default. Each scheduler pass
+     * drops the row content of snapshots that are superseded, past their
+     * recovery grace and not owed to any caller (receipts, current
+     * `received` / `unreadable` / `content_mismatch` statements), while every
+     * revision's metadata stays. Official revisions are never compacted. Uses
+     * this service's `statusRetentionDays` and `automatedRecoveryWindowSeconds`.
+     * The protocol takes compaction into effect only in the next eligible minor
+     * after November 20, 2026: do not enable this in production before then.
+     */
+    compaction?: ReportingCompactionOptionsV1;
     /**
      * Maintain the host change feed (`changesAfter`, `getCurrentRevision`,
      * `listCurrentRevisions` on `stores.core`). Adds
@@ -329,4 +359,4 @@ export interface PostgresReliableReportingProductionServiceV1<TCtxMeta = Record<
  */
 export declare function createPostgresReliableReportingProductionService<TCtxMeta = Record<string, unknown>>(options: CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta>): Promise<PostgresReliableReportingProductionServiceV1<TCtxMeta>>;
 export * from './conformance';
-export { ReportingMaintenancePartialFailureError, type ReportingChangeFeedMaintenanceOptionsV1, type ReportingLedgerMaintenanceStoreV1, type ReportingLedgerMaintenanceTaskNameV1, type ReportingLedgerMaintenanceTaskResultV1, type ReportingRetentionOptionsV1, } from './maintenance';
+export { ReportingMaintenancePartialFailureError, type ReportingChangeFeedMaintenanceOptionsV1, type ReportingCompactionOptionsV1, type ReportingLedgerMaintenanceStoreV1, type ReportingLedgerMaintenanceTaskNameV1, type ReportingLedgerMaintenanceTaskResultV1, type ReportingRetentionOptionsV1, } from './maintenance';

package/dist/lib/reporting/service/index.js

@@ -108,7 +108,12 @@ function createReliableReportingService(options) {
       throw new TypeError("maintenance must be an options object");
     }
     const candidate = options.store;
-    for (const method of ["retireExpiredPeriods", "pruneChanges", "sweepRowWriteIntents"]) {
+    for (const method of [
+      "retireExpiredPeriods",
+      "pruneChanges",
+      "sweepRowWriteIntents",
+      ...maintenance.compaction ? ["compactSupersededSnapshots"] : []
+    ]) {
       if (typeof candidate[method] !== "function") {
         throw new TypeError(
           `maintenance requires a PostgresReportingLedgerStore (or a store with ${method}); the configured store cannot run ledger maintenance`
@@ -116,6 +121,9 @@ function createReliableReportingService(options) {
       }
     }
     maintenanceStore = candidate;
+    if (maintenance.compaction) {
+      candidate.assertCompactionSafeRowBindings?.();
+    }
     if (maintenance.changeFeed && maintenanceStore.changeFeedEnabled === false) {
       throw new TypeError(
         "maintenance.changeFeed requires the store to be built with changeFeed: true; otherwise pruning silently does nothing"
@@ -131,7 +139,9 @@ function createReliableReportingService(options) {
     store: maintenanceStore,
     ...typeof maintenanceStore.sweepExpiredState === "function" ? { sweepSnapshots: (limit) => maintenanceStore.sweepExpiredState(limit) } : {},
     statusRetentionDays: retentionDays,
+    automatedRecoveryWindowSeconds: options.automatedRecoveryWindowSeconds,
     retention: maintenance.retention,
+    compaction: maintenance.compaction,
     changeFeed: maintenance.changeFeed,
     signal,
     ...report ? { report } : {}
@@ -152,7 +162,10 @@ function createReliableReportingService(options) {
     resolveConsumerId: options.resolveConsumerId,
     ...effectiveConsumerMismatchEscalation ? { consumerMismatchEscalation: effectiveConsumerMismatchEscalation } : {}
   }) : (0, import_ledger.createReportingStatusHandler)(options.store);
-  const getMediaBuyDelivery = (0, import_ledger.createReportingDeliveryHandler)(options.store);
+  const getMediaBuyDelivery = (0, import_ledger.createReportingDeliveryHandler)(
+    options.store,
+    options.legacyRevisionReader ? { legacyRevisionReader: options.legacyRevisionReader } : {}
+  );
   const syncReportingStatus = options.resolveConsumerId ? (0, import_ledger.createSyncReportingStatusHandler)(options.store, {
     resolveConsumerId: options.resolveConsumerId
   }) : void 0;
@@ -356,6 +369,7 @@ async function createPostgresReliableReportingProductionService(options) {
   if (typeof options.activity?.tenantScopeForAccount !== "function") {
     throw new TypeError("Reliable Reporting production service requires activity.tenantScopeForAccount");
   }
+  (0, import_maintenance.assertReportingLedgerMaintenanceOptions)({ compaction: options.compaction }, options.statusRetentionDays);
   if (Object.values(options.adapters).some(
     (adapter) => adapter.deliveryOffering.reconciliation_mode === "consumer_receipt"
   ) && typeof options.obligatedConsumers !== "function") {
@@ -427,6 +441,7 @@ async function createPostgresReliableReportingProductionService(options) {
     ...options.rowStorage ? { rowStorage: options.rowStorage } : {},
     ...options.changeFeed ? { changeFeed: true } : {}
   });
+  if (options.compaction) coreStore.assertCompactionSafeRowBindings();
   const managedStore = new import_ledger.PostgresReportingManagedDeliveryStore(options.db, {
     ...options.managedDelivery.store,
     statusRetentionDays: options.statusRetentionDays,
@@ -455,6 +470,7 @@ async function createPostgresReliableReportingProductionService(options) {
   await webhookActivity.probe();
   const managed = await (0, import_ledger.createReportingManagedDeliveryRuntime)({
     coreStore,
+    ...options.legacyRevisionReader ? { legacyRevisionReader: options.legacyRevisionReader } : {},
     store: managedStore,
     adapter: options.managedDelivery.adapter,
     offerings: core.capabilities.offerings,
@@ -563,7 +579,9 @@ async function createPostgresReliableReportingProductionService(options) {
       store: coreStore,
       sweepSnapshots: (limit) => (0, import_ledger.sweepExpiredReportingLedgerState)(options.db, limit),
       statusRetentionDays: options.statusRetentionDays,
+      automatedRecoveryWindowSeconds: options.automatedRecoveryWindowSeconds,
       retention: options.retention,
+      compaction: options.compaction,
       changeFeed: options.changeFeed,
       signal,
       report: (error) => reportAuxiliaryError(scheduler, error)

package/dist/lib/reporting/service/index.mjs

@@ -119,7 +119,12 @@ function createReliableReportingService(options) {
       throw new TypeError("maintenance must be an options object");
     }
     const candidate = options.store;
-    for (const method of ["retireExpiredPeriods", "pruneChanges", "sweepRowWriteIntents"]) {
+    for (const method of [
+      "retireExpiredPeriods",
+      "pruneChanges",
+      "sweepRowWriteIntents",
+      ...maintenance.compaction ? ["compactSupersededSnapshots"] : []
+    ]) {
       if (typeof candidate[method] !== "function") {
         throw new TypeError(
           `maintenance requires a PostgresReportingLedgerStore (or a store with ${method}); the configured store cannot run ledger maintenance`
@@ -127,6 +132,9 @@ function createReliableReportingService(options) {
       }
     }
     maintenanceStore = candidate;
+    if (maintenance.compaction) {
+      candidate.assertCompactionSafeRowBindings?.();
+    }
     if (maintenance.changeFeed && maintenanceStore.changeFeedEnabled === false) {
       throw new TypeError(
         "maintenance.changeFeed requires the store to be built with changeFeed: true; otherwise pruning silently does nothing"
@@ -142,7 +150,9 @@ function createReliableReportingService(options) {
     store: maintenanceStore,
     ...typeof maintenanceStore.sweepExpiredState === "function" ? { sweepSnapshots: (limit) => maintenanceStore.sweepExpiredState(limit) } : {},
     statusRetentionDays: retentionDays,
+    automatedRecoveryWindowSeconds: options.automatedRecoveryWindowSeconds,
     retention: maintenance.retention,
+    compaction: maintenance.compaction,
     changeFeed: maintenance.changeFeed,
     signal,
     ...report ? { report } : {}
@@ -163,7 +173,10 @@ function createReliableReportingService(options) {
     resolveConsumerId: options.resolveConsumerId,
     ...effectiveConsumerMismatchEscalation ? { consumerMismatchEscalation: effectiveConsumerMismatchEscalation } : {}
   }) : createReportingStatusHandler(options.store);
-  const getMediaBuyDelivery = createReportingDeliveryHandler(options.store);
+  const getMediaBuyDelivery = createReportingDeliveryHandler(
+    options.store,
+    options.legacyRevisionReader ? { legacyRevisionReader: options.legacyRevisionReader } : {}
+  );
   const syncReportingStatus = options.resolveConsumerId ? createSyncReportingStatusHandler(options.store, {
     resolveConsumerId: options.resolveConsumerId
   }) : void 0;
@@ -367,6 +380,7 @@ async function createPostgresReliableReportingProductionService(options) {
   if (typeof options.activity?.tenantScopeForAccount !== "function") {
     throw new TypeError("Reliable Reporting production service requires activity.tenantScopeForAccount");
   }
+  assertReportingLedgerMaintenanceOptions({ compaction: options.compaction }, options.statusRetentionDays);
   if (Object.values(options.adapters).some(
     (adapter) => adapter.deliveryOffering.reconciliation_mode === "consumer_receipt"
   ) && typeof options.obligatedConsumers !== "function") {
@@ -438,6 +452,7 @@ async function createPostgresReliableReportingProductionService(options) {
     ...options.rowStorage ? { rowStorage: options.rowStorage } : {},
     ...options.changeFeed ? { changeFeed: true } : {}
   });
+  if (options.compaction) coreStore.assertCompactionSafeRowBindings();
   const managedStore = new PostgresReportingManagedDeliveryStore(options.db, {
     ...options.managedDelivery.store,
     statusRetentionDays: options.statusRetentionDays,
@@ -466,6 +481,7 @@ async function createPostgresReliableReportingProductionService(options) {
   await webhookActivity.probe();
   const managed = await createReportingManagedDeliveryRuntime({
     coreStore,
+    ...options.legacyRevisionReader ? { legacyRevisionReader: options.legacyRevisionReader } : {},
     store: managedStore,
     adapter: options.managedDelivery.adapter,
     offerings: core.capabilities.offerings,
@@ -574,7 +590,9 @@ async function createPostgresReliableReportingProductionService(options) {
       store: coreStore,
       sweepSnapshots: (limit) => sweepExpiredReportingLedgerState(options.db, limit),
       statusRetentionDays: options.statusRetentionDays,
+      automatedRecoveryWindowSeconds: options.automatedRecoveryWindowSeconds,
       retention: options.retention,
+      compaction: options.compaction,
       changeFeed: options.changeFeed,
       signal,
       report: (error) => reportAuxiliaryError(scheduler, error)

package/dist/lib/reporting/service/maintenance.d.mts

@@ -11,18 +11,33 @@ export interface ReportingRetentionOptionsV1 {
     recordRetentionDays?: number;
     limit?: number;
 }
+/**
+ * Opt-in compaction of superseded snapshot revisions to metadata only, as
+ * adcontextprotocol/adcp#8100 permits. Off unless `enabled: true`. Uses the
+ * service's `statusRetentionDays` and `automatedRecoveryWindowSeconds`, so it
+ * can never drop content earlier than the commitments advertised to buyers.
+ *
+ * Compaction takes effect in the AdCP release after November 20, 2026; do not
+ * enable it in production before then. See `docs/guides/REPORTING-OPERATIONS.md`.
+ */
+export interface ReportingCompactionOptionsV1 {
+    enabled: true;
+    /** Revisions compacted per pass. Defaults to 100. */
+    limit?: number;
+}
 /** Change-feed pruning window and the consumer hold shared with retention. */
 export type ReportingChangeFeedMaintenanceOptionsV1 = boolean | {
     changeRetentionDays?: number;
     maxFeedHoldDays?: number;
 };
 /** The ledger-store surface a maintenance pass drives. */
-export type ReportingLedgerMaintenanceStoreV1 = Pick<PostgresReportingLedgerStore, 'sweepRowWriteIntents' | 'pruneChanges' | 'retireExpiredPeriods'>;
+export type ReportingLedgerMaintenanceStoreV1 = Pick<PostgresReportingLedgerStore, 'sweepRowWriteIntents' | 'pruneChanges' | 'retireExpiredPeriods'> & Partial<Pick<PostgresReportingLedgerStore, 'compactSupersededSnapshots'>>;
 interface ReportingLedgerMaintenanceTaskOutcomesV1 {
     'snapshot sweep': Awaited<ReturnType<PostgresReportingLedgerStore['sweepExpiredState']>>;
     'row upload sweep': Awaited<ReturnType<PostgresReportingLedgerStore['sweepRowWriteIntents']>>;
     'change-feed pruning': Awaited<ReturnType<PostgresReportingLedgerStore['pruneChanges']>>;
     retention: Awaited<ReturnType<PostgresReportingLedgerStore['retireExpiredPeriods']>>;
+    'snapshot compaction': Awaited<ReturnType<PostgresReportingLedgerStore['compactSupersededSnapshots']>>;
 }
 export type ReportingLedgerMaintenanceTaskNameV1 = keyof ReportingLedgerMaintenanceTaskOutcomesV1;
 /**
@@ -62,7 +77,10 @@ export interface RunReportingLedgerMaintenanceInputV1 {
      */
     sweepSnapshots?: (limit: number) => Promise<ReportingLedgerMaintenanceTaskOutcomesV1['snapshot sweep']>;
     statusRetentionDays: number;
+    /** The service's advertised `automated_recovery_window_seconds`; required when `compaction` is enabled. */
+    automatedRecoveryWindowSeconds?: number | undefined;
     retention?: ReportingRetentionOptionsV1 | undefined;
+    compaction?: ReportingCompactionOptionsV1 | undefined;
     changeFeed?: ReportingChangeFeedMaintenanceOptionsV1 | undefined;
     signal?: AbortSignal | undefined;
     /**
@@ -86,6 +104,7 @@ export declare function runReportingLedgerMaintenance(input: RunReportingLedgerM
  */
 export declare function assertReportingLedgerMaintenanceOptions(input: {
     retention?: ReportingRetentionOptionsV1 | undefined;
+    compaction?: ReportingCompactionOptionsV1 | undefined;
     changeFeed?: ReportingChangeFeedMaintenanceOptionsV1 | undefined;
 }, statusRetentionDays: number): void;
 export {};

package/dist/lib/reporting/service/maintenance.d.ts

@@ -11,18 +11,33 @@ export interface ReportingRetentionOptionsV1 {
     recordRetentionDays?: number;
     limit?: number;
 }
+/**
+ * Opt-in compaction of superseded snapshot revisions to metadata only, as
+ * adcontextprotocol/adcp#8100 permits. Off unless `enabled: true`. Uses the
+ * service's `statusRetentionDays` and `automatedRecoveryWindowSeconds`, so it
+ * can never drop content earlier than the commitments advertised to buyers.
+ *
+ * Compaction takes effect in the AdCP release after November 20, 2026; do not
+ * enable it in production before then. See `docs/guides/REPORTING-OPERATIONS.md`.
+ */
+export interface ReportingCompactionOptionsV1 {
+    enabled: true;
+    /** Revisions compacted per pass. Defaults to 100. */
+    limit?: number;
+}
 /** Change-feed pruning window and the consumer hold shared with retention. */
 export type ReportingChangeFeedMaintenanceOptionsV1 = boolean | {
     changeRetentionDays?: number;
     maxFeedHoldDays?: number;
 };
 /** The ledger-store surface a maintenance pass drives. */
-export type ReportingLedgerMaintenanceStoreV1 = Pick<PostgresReportingLedgerStore, 'sweepRowWriteIntents' | 'pruneChanges' | 'retireExpiredPeriods'>;
+export type ReportingLedgerMaintenanceStoreV1 = Pick<PostgresReportingLedgerStore, 'sweepRowWriteIntents' | 'pruneChanges' | 'retireExpiredPeriods'> & Partial<Pick<PostgresReportingLedgerStore, 'compactSupersededSnapshots'>>;
 interface ReportingLedgerMaintenanceTaskOutcomesV1 {
     'snapshot sweep': Awaited<ReturnType<PostgresReportingLedgerStore['sweepExpiredState']>>;
     'row upload sweep': Awaited<ReturnType<PostgresReportingLedgerStore['sweepRowWriteIntents']>>;
     'change-feed pruning': Awaited<ReturnType<PostgresReportingLedgerStore['pruneChanges']>>;
     retention: Awaited<ReturnType<PostgresReportingLedgerStore['retireExpiredPeriods']>>;
+    'snapshot compaction': Awaited<ReturnType<PostgresReportingLedgerStore['compactSupersededSnapshots']>>;
 }
 export type ReportingLedgerMaintenanceTaskNameV1 = keyof ReportingLedgerMaintenanceTaskOutcomesV1;
 /**
@@ -62,7 +77,10 @@ export interface RunReportingLedgerMaintenanceInputV1 {
      */
     sweepSnapshots?: (limit: number) => Promise<ReportingLedgerMaintenanceTaskOutcomesV1['snapshot sweep']>;
     statusRetentionDays: number;
+    /** The service's advertised `automated_recovery_window_seconds`; required when `compaction` is enabled. */
+    automatedRecoveryWindowSeconds?: number | undefined;
     retention?: ReportingRetentionOptionsV1 | undefined;
+    compaction?: ReportingCompactionOptionsV1 | undefined;
     changeFeed?: ReportingChangeFeedMaintenanceOptionsV1 | undefined;
     signal?: AbortSignal | undefined;
     /**
@@ -86,6 +104,7 @@ export declare function runReportingLedgerMaintenance(input: RunReportingLedgerM
  */
 export declare function assertReportingLedgerMaintenanceOptions(input: {
     retention?: ReportingRetentionOptionsV1 | undefined;
+    compaction?: ReportingCompactionOptionsV1 | undefined;
     changeFeed?: ReportingChangeFeedMaintenanceOptionsV1 | undefined;
 }, statusRetentionDays: number): void;
 export {};

package/dist/lib/reporting/service/maintenance.js

@@ -38,7 +38,7 @@ class ReportingMaintenancePartialFailureError extends Error {
   failedIds;
 }
 async function runReportingLedgerMaintenance(input) {
-  const { store, signal, changeFeed, retention } = input;
+  const { store, signal, changeFeed, retention, compaction } = input;
   const start = (name, run) => {
     try {
       return [name, run()];
@@ -71,6 +71,23 @@ async function runReportingLedgerMaintenance(input) {
           ...signal ? { signal } : {}
         })
       )
+    ] : [],
+    ...compaction?.enabled ? [
+      start("snapshot compaction", () => {
+        if (typeof store.compactSupersededSnapshots !== "function") {
+          throw new TypeError("compaction requires a store with compactSupersededSnapshots");
+        }
+        if (input.automatedRecoveryWindowSeconds === void 0) {
+          throw new TypeError("compaction requires automatedRecoveryWindowSeconds");
+        }
+        return store.compactSupersededSnapshots({
+          statusRetentionDays: input.statusRetentionDays,
+          automatedRecoveryWindowSeconds: input.automatedRecoveryWindowSeconds,
+          ...typeof changeFeed === "object" && changeFeed.maxFeedHoldDays !== void 0 ? { maxFeedHoldDays: changeFeed.maxFeedHoldDays } : {},
+          limit: compaction.limit ?? 100,
+          ...signal ? { signal } : {}
+        });
+      })
     ] : []
   ];
   const settled = await Promise.allSettled(tasks.map(([, task]) => task));
@@ -108,7 +125,13 @@ function assertReportingLedgerMaintenanceOptions(input, statusRetentionDays) {
       throw new TypeError(`${field} must be a positive safe integer`);
     }
   };
-  const { retention, changeFeed } = input;
+  const { retention, changeFeed, compaction } = input;
+  if (compaction !== void 0) {
+    if (compaction === null || typeof compaction !== "object" || compaction.enabled !== true) {
+      throw new TypeError("maintenance.compaction must be { enabled: true, ... }");
+    }
+    if (compaction.limit !== void 0) positive(compaction.limit, "maintenance.compaction.limit");
+  }
   if (retention !== void 0) {
     if (retention === null || typeof retention !== "object" || retention.enabled !== true) {
       throw new TypeError("maintenance.retention must be { enabled: true, ... }");

package/dist/lib/reporting/service/maintenance.mjs

@@ -13,7 +13,7 @@ class ReportingMaintenancePartialFailureError extends Error {
   failedIds;
 }
 async function runReportingLedgerMaintenance(input) {
-  const { store, signal, changeFeed, retention } = input;
+  const { store, signal, changeFeed, retention, compaction } = input;
   const start = (name, run) => {
     try {
       return [name, run()];
@@ -46,6 +46,23 @@ async function runReportingLedgerMaintenance(input) {
           ...signal ? { signal } : {}
         })
       )
+    ] : [],
+    ...compaction?.enabled ? [
+      start("snapshot compaction", () => {
+        if (typeof store.compactSupersededSnapshots !== "function") {
+          throw new TypeError("compaction requires a store with compactSupersededSnapshots");
+        }
+        if (input.automatedRecoveryWindowSeconds === void 0) {
+          throw new TypeError("compaction requires automatedRecoveryWindowSeconds");
+        }
+        return store.compactSupersededSnapshots({
+          statusRetentionDays: input.statusRetentionDays,
+          automatedRecoveryWindowSeconds: input.automatedRecoveryWindowSeconds,
+          ...typeof changeFeed === "object" && changeFeed.maxFeedHoldDays !== void 0 ? { maxFeedHoldDays: changeFeed.maxFeedHoldDays } : {},
+          limit: compaction.limit ?? 100,
+          ...signal ? { signal } : {}
+        });
+      })
     ] : []
   ];
   const settled = await Promise.allSettled(tasks.map(([, task]) => task));
@@ -83,7 +100,13 @@ function assertReportingLedgerMaintenanceOptions(input, statusRetentionDays) {
       throw new TypeError(`${field} must be a positive safe integer`);
     }
   };
-  const { retention, changeFeed } = input;
+  const { retention, changeFeed, compaction } = input;
+  if (compaction !== void 0) {
+    if (compaction === null || typeof compaction !== "object" || compaction.enabled !== true) {
+      throw new TypeError("maintenance.compaction must be { enabled: true, ... }");
+    }
+    if (compaction.limit !== void 0) positive(compaction.limit, "maintenance.compaction.limit");
+  }
   if (retention !== void 0) {
     if (retention === null || typeof retention !== "object" || retention.enabled !== true) {
       throw new TypeError("maintenance.retention must be { enabled: true, ... }");

package/dist/lib/schemas-data/v2.5/_provenance.json

@@ -4,5 +4,5 @@
   "source_sha": "4e553ad955f83b49c7d221ab5c3ff78237ad02e3",
   "source_tarball_sha256": "580656d6466ef9f0d1119985e6726c2efea718dc671e2ad30957fcb2fd54af0f",
   "upstream_adcp_version": "2.5.3",
-  "synced_at": "2026-10-10T13:31:54.379Z"
+  "synced_at": "2026-10-11T13:22:33.550Z"
 }

package/dist/lib/testing/storyboard/request-builder.js

@@ -32,25 +32,25 @@ const UNKNOWN_FORMAT_ID = Object.freeze({ agent_url: "https://unknown.example.co
 const FALLBACK_CALLER_AGENT_URL = "https://e2e-orchestrator.adcontextprotocol.org/";
 const FIXTURE_AWARE_ENRICHERS = /* @__PURE__ */ new Set([
   "create_media_buy",
-  // merges discovery-derived product_id / pricing_option_id INTO fixture packages[0]
+  // preserves authored accounts and merges discovered identifiers INTO fixture packages[0]
   "comply_test_controller",
   // forces account.sandbox: true regardless of fixture
   "check_governance",
   // preserves the authored intent-vs-delivery request shape
   "get_products",
-  // preserves wholesale fixture fields while keeping resolved account scope authoritative
+  // preserves discovery fields and authored account identities
   "get_signals",
-  // preserves discovery fields while keeping async task account scope authoritative
+  // preserves discovery fields and authored account identities
   "get_task_status",
-  // preserves task filters while keeping resolved account scope authoritative
+  // preserves task filters and authored account identities
   "list_tasks",
-  // preserves reconciliation filters while keeping resolved account scope authoritative
+  // preserves reconciliation filters and authored account identities
   "update_media_buy",
-  // resolves account via resolveAccount(options) so sandbox routing matches create_media_buy
+  // fills missing account identity and carries sandbox routing into authored natural keys
   "get_media_buys",
-  // resolves account via resolveAccount(options) so sandbox routing matches create_media_buy
+  // fills missing account identity and carries sandbox routing into authored natural keys
   "get_media_buy_delivery"
-  // resolves account via resolveAccount(options) so sandbox routing matches create_media_buy
+  // fills missing account identity and carries sandbox routing into authored natural keys
 ]);
 function hasUnresolvedContextReference(value) {
   if (typeof value === "string") return /^\$context\.\w+$/.test(value);
@@ -93,23 +93,21 @@ function runClockMs(runnerVars) {
   return runnerVars?.runStartMs ?? Date.now();
 }
 function resolveMediaBuyAccount(fixtureAccount, contextAccount, options) {
-  const resolvedAccount = contextAccount ?? (0, import_client.resolveAccount)(options);
-  if (contextAccount === void 0 && fixtureAccount !== null && typeof fixtureAccount === "object" && !Array.isArray(fixtureAccount) && typeof fixtureAccount.operator === "string" && typeof fixtureAccount.account_id !== "string") {
-    const sandbox = resolvedAccount.sandbox;
+  if (hasAuthoredAccountIdentity(fixtureAccount)) {
+    if (hasUnresolvedContextReference(fixtureAccount)) return fixtureAccount;
+    if (typeof fixtureAccount.account_id === "string") return fixtureAccount;
+    const sandbox = contextAccount?.sandbox ?? (0, import_client.resolveAccount)(options).sandbox;
     return {
       ...fixtureAccount,
       ...sandbox !== void 0 && { sandbox }
     };
   }
-  return resolvedAccount;
+  return contextAccount ?? (0, import_client.resolveAccount)(options);
 }
 function resolveDiscoveryAccount(task, fixtureAccount, contextAccount, options) {
-  if (import_account_policy.ACCOUNT_FREE_DISCOVERY_TASKS.has(task) && contextAccount === void 0 && hasUnresolvedContextReference(fixtureAccount))
-    return void 0;
+  if (import_account_policy.ACCOUNT_FREE_DISCOVERY_TASKS.has(task) && hasUnresolvedContextReference(fixtureAccount)) return contextAccount;
   if (import_account_policy.ACCOUNT_FREE_DISCOVERY_TASKS.has(task) && fixtureAccount === void 0 && contextAccount === void 0)
     return void 0;
-  if (contextAccount === void 0 && fixtureAccount && typeof fixtureAccount === "object" && "account_id" in fixtureAccount)
-    return fixtureAccount;
   return resolveMediaBuyAccount(fixtureAccount, contextAccount, options);
 }
 const OPERATION_SCOPED_CONTROLLER_SCENARIOS = /* @__PURE__ */ new Set([