@adcp/sdk 15.3.0 → 15.5.0

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

@@ -198,6 +198,21 @@ export interface ReportingLedgerAdjustmentV1 {
 }
 export type ReportingLedgerRevisionSnapshotV1 = Omit<ReportingLedgerRevisionV1, 'rows'>;
 export type ReportingLedgerRevisionMetadataV1 = Omit<ReportingLedgerRevisionV1, 'rows'>;
+export type ReportingLedgerAdjustmentMetadataV1 = Omit<ReportingLedgerAdjustmentV1, 'rows'>;
+export interface ReportingRevisionRowsReadV1 {
+    reporting_revision_id: string;
+    account_id: string;
+    /** Zero-based ordinal of the first row to return. */
+    offset: number;
+    /** Maximum rows to return; at least 1. */
+    limit: number;
+    signal?: AbortSignal;
+}
+export interface ReportingRevisionRowsPageV1 {
+    rows: Record<string, unknown>[];
+    /** Total rows in the revision. */
+    total: number;
+}
 export type ReportingLedgerAdjustmentSnapshotV1 = Omit<ReportingLedgerAdjustmentV1, 'rows'>;
 export interface ReportingLedgerConsumerStatusV1 {
     consumerStatusId: string;
@@ -741,6 +756,14 @@ export interface ReportingLedgerStore {
     }>;
     getObligation(reporting_obligation_id: string, account_id?: string): Promise<ReportingLedgerObligationV1 | null>;
     listObligations(account_id?: string): Promise<ReportingLedgerObligationV1[]>;
+    /**
+     * Optional: periods whose ledger records were retired by retention. The
+     * planner treats them as already covered so it never re-creates them.
+     */
+    listRetiredObligationOrdinals?(account_id?: string): Promise<{
+        configurationId: string;
+        periodOrdinal: number;
+    }[]>;
     listLifecycleDueObligations(input: {
         ledgerAsOf: string;
         account_id?: string;
@@ -761,12 +784,34 @@ export interface ReportingLedgerStore {
     }>;
     /** Returns an exact row-bearing revision only when it belongs to the resolved account. */
     getRevision(reporting_revision_id: string, account_id: string): Promise<ReportingLedgerRevisionV1 | null>;
+    /**
+     * Optional row-free counterpart of `getRevision`, scoped to the resolved
+     * account. Exact-read handlers prefer it so they never load every row to
+     * serve one page.
+     */
+    getRevisionMetadata?(reporting_revision_id: string, account_id: string): Promise<ReportingLedgerRevisionMetadataV1 | null>;
+    /**
+     * Optional: one page of a revision's rows in ordinal order, only when the
+     * revision belongs to the resolved account. `total` is the revision's row
+     * count. Stores that keep rows outside the revision document verify every
+     * row they return against the committed binding before returning it.
+     */
+    readRevisionRows?(input: ReportingRevisionRowsReadV1): Promise<ReportingRevisionRowsPageV1 | null>;
     listRevisions(reporting_obligation_id: string): Promise<ReportingLedgerRevisionV1[]>;
+    /**
+     * Optional: every retained revision for one obligation without
+     * materializing rows. The producer, lifecycle reconciler and status ingest
+     * prefer it and otherwise fall back to `listRevisions` with rows dropped.
+     * When `account_id` is supplied, only that account's revisions are returned.
+     */
+    listRevisionMetadata?(reporting_obligation_id: string, account_id?: string): Promise<ReportingLedgerRevisionMetadataV1[]>;
     commitAdjustment(adjustment: ReportingLedgerAdjustmentV1, lease: ReportingLedgerLeaseV1): Promise<{
         inserted: boolean;
         value: ReportingLedgerAdjustmentV1;
     }>;
     listAdjustments(reporting_obligation_id: string): Promise<ReportingLedgerAdjustmentV1[]>;
+    /** Optional row-free counterpart of `listAdjustments`, preferred when present. */
+    listAdjustmentMetadata?(reporting_obligation_id: string): Promise<ReportingLedgerAdjustmentMetadataV1[]>;
     putConsumerStatus(status: ReportingLedgerConsumerStatusV1): Promise<{
         inserted: boolean;
         value: ReportingLedgerConsumerStatusV1;

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

@@ -198,6 +198,21 @@ export interface ReportingLedgerAdjustmentV1 {
 }
 export type ReportingLedgerRevisionSnapshotV1 = Omit<ReportingLedgerRevisionV1, 'rows'>;
 export type ReportingLedgerRevisionMetadataV1 = Omit<ReportingLedgerRevisionV1, 'rows'>;
+export type ReportingLedgerAdjustmentMetadataV1 = Omit<ReportingLedgerAdjustmentV1, 'rows'>;
+export interface ReportingRevisionRowsReadV1 {
+    reporting_revision_id: string;
+    account_id: string;
+    /** Zero-based ordinal of the first row to return. */
+    offset: number;
+    /** Maximum rows to return; at least 1. */
+    limit: number;
+    signal?: AbortSignal;
+}
+export interface ReportingRevisionRowsPageV1 {
+    rows: Record<string, unknown>[];
+    /** Total rows in the revision. */
+    total: number;
+}
 export type ReportingLedgerAdjustmentSnapshotV1 = Omit<ReportingLedgerAdjustmentV1, 'rows'>;
 export interface ReportingLedgerConsumerStatusV1 {
     consumerStatusId: string;
@@ -741,6 +756,14 @@ export interface ReportingLedgerStore {
     }>;
     getObligation(reporting_obligation_id: string, account_id?: string): Promise<ReportingLedgerObligationV1 | null>;
     listObligations(account_id?: string): Promise<ReportingLedgerObligationV1[]>;
+    /**
+     * Optional: periods whose ledger records were retired by retention. The
+     * planner treats them as already covered so it never re-creates them.
+     */
+    listRetiredObligationOrdinals?(account_id?: string): Promise<{
+        configurationId: string;
+        periodOrdinal: number;
+    }[]>;
     listLifecycleDueObligations(input: {
         ledgerAsOf: string;
         account_id?: string;
@@ -761,12 +784,34 @@ export interface ReportingLedgerStore {
     }>;
     /** Returns an exact row-bearing revision only when it belongs to the resolved account. */
     getRevision(reporting_revision_id: string, account_id: string): Promise<ReportingLedgerRevisionV1 | null>;
+    /**
+     * Optional row-free counterpart of `getRevision`, scoped to the resolved
+     * account. Exact-read handlers prefer it so they never load every row to
+     * serve one page.
+     */
+    getRevisionMetadata?(reporting_revision_id: string, account_id: string): Promise<ReportingLedgerRevisionMetadataV1 | null>;
+    /**
+     * Optional: one page of a revision's rows in ordinal order, only when the
+     * revision belongs to the resolved account. `total` is the revision's row
+     * count. Stores that keep rows outside the revision document verify every
+     * row they return against the committed binding before returning it.
+     */
+    readRevisionRows?(input: ReportingRevisionRowsReadV1): Promise<ReportingRevisionRowsPageV1 | null>;
     listRevisions(reporting_obligation_id: string): Promise<ReportingLedgerRevisionV1[]>;
+    /**
+     * Optional: every retained revision for one obligation without
+     * materializing rows. The producer, lifecycle reconciler and status ingest
+     * prefer it and otherwise fall back to `listRevisions` with rows dropped.
+     * When `account_id` is supplied, only that account's revisions are returned.
+     */
+    listRevisionMetadata?(reporting_obligation_id: string, account_id?: string): Promise<ReportingLedgerRevisionMetadataV1[]>;
     commitAdjustment(adjustment: ReportingLedgerAdjustmentV1, lease: ReportingLedgerLeaseV1): Promise<{
         inserted: boolean;
         value: ReportingLedgerAdjustmentV1;
     }>;
     listAdjustments(reporting_obligation_id: string): Promise<ReportingLedgerAdjustmentV1[]>;
+    /** Optional row-free counterpart of `listAdjustments`, preferred when present. */
+    listAdjustmentMetadata?(reporting_obligation_id: string): Promise<ReportingLedgerAdjustmentMetadataV1[]>;
     putConsumerStatus(status: ReportingLedgerConsumerStatusV1): Promise<{
         inserted: boolean;
         value: ReportingLedgerConsumerStatusV1;

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

@@ -4,7 +4,7 @@ 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 ReportingSourceWithReaderV1 } from '../ledger/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 { type PostgresReportingWebhookActivityV1 } from '../webhook-activity.mjs';
 import type { InlineReportingReplayRetentionV1 } from '../source/index.mjs';
 import { type InlineReportingDeliveryFetchV1, type ReportingSourceOfferingV1 } from '../source/index.mjs';
@@ -196,6 +196,35 @@ export type CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta =
     publisherScope: string;
     /** Explicit acknowledgement required by the authoritative Core store. */
     acknowledgeIsolatedDatabase: true;
+    /**
+     * Store new revision rows as verified canonical JSONL chunks. Adds
+     * `REPORTING_ROW_STORAGE_MIGRATION` (PostgreSQL 13+) to `setup.migrations`
+     * and probes it before publishing capabilities.
+     */
+    rowStorage?: boolean | ReportingRowStorageOptionsV1;
+    /**
+     * Opt in to period-aligned retention. Each scheduler pass retires whole
+     * periods once `max(statusRetentionDays, recordRetentionDays)` has elapsed
+     * since both the period end and its latest publication, deleting their
+     * rows and ledger records and leaving a tombstone. Abandoned row uploads
+     * and expired cursor snapshots are always swept.
+     */
+    retention?: {
+        enabled: true;
+        recordRetentionDays?: number;
+        limit?: number;
+    };
+    /**
+     * Maintain the host change feed (`changesAfter`, `getCurrentRevision`,
+     * `listCurrentRevisions` on `stores.core`). Adds
+     * `REPORTING_LEDGER_CHANGES_MIGRATION` (PostgreSQL 13+); the scheduler prunes
+     * changes older than `changeRetentionDays` (default 30) unless a registered
+     * consumer updated within `maxFeedHoldDays` (default 7) still needs them.
+     */
+    changeFeed?: boolean | {
+        changeRetentionDays?: number;
+        maxFeedHoldDays?: number;
+    };
     notifications: ProductionNotificationOptions;
     managedDelivery: {
         adapter: ReportingManagedDeliveryAdapterV1;
@@ -273,3 +302,14 @@ export interface PostgresReliableReportingProductionServiceV1<TCtxMeta = Record<
  */
 export declare function createPostgresReliableReportingProductionService<TCtxMeta = Record<string, unknown>>(options: CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta>): Promise<PostgresReliableReportingProductionServiceV1<TCtxMeta>>;
 export * from './conformance.mjs';
+/**
+ * A scheduled maintenance pass completed but could not process some items
+ * (for example, a retention period whose objects could not be deleted). The
+ * pass resumes them next time; repeated reports need operator attention.
+ */
+export declare class ReportingMaintenancePartialFailureError extends Error {
+    readonly task: string;
+    readonly failedCount: number;
+    readonly failedIds: readonly string[];
+    constructor(task: string, failedCount: number, failedIds: readonly string[]);
+}

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

@@ -4,7 +4,7 @@ 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 ReportingSourceWithReaderV1 } from '../ledger';
+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 { type PostgresReportingWebhookActivityV1 } from '../webhook-activity';
 import type { InlineReportingReplayRetentionV1 } from '../source';
 import { type InlineReportingDeliveryFetchV1, type ReportingSourceOfferingV1 } from '../source';
@@ -196,6 +196,35 @@ export type CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta =
     publisherScope: string;
     /** Explicit acknowledgement required by the authoritative Core store. */
     acknowledgeIsolatedDatabase: true;
+    /**
+     * Store new revision rows as verified canonical JSONL chunks. Adds
+     * `REPORTING_ROW_STORAGE_MIGRATION` (PostgreSQL 13+) to `setup.migrations`
+     * and probes it before publishing capabilities.
+     */
+    rowStorage?: boolean | ReportingRowStorageOptionsV1;
+    /**
+     * Opt in to period-aligned retention. Each scheduler pass retires whole
+     * periods once `max(statusRetentionDays, recordRetentionDays)` has elapsed
+     * since both the period end and its latest publication, deleting their
+     * rows and ledger records and leaving a tombstone. Abandoned row uploads
+     * and expired cursor snapshots are always swept.
+     */
+    retention?: {
+        enabled: true;
+        recordRetentionDays?: number;
+        limit?: number;
+    };
+    /**
+     * Maintain the host change feed (`changesAfter`, `getCurrentRevision`,
+     * `listCurrentRevisions` on `stores.core`). Adds
+     * `REPORTING_LEDGER_CHANGES_MIGRATION` (PostgreSQL 13+); the scheduler prunes
+     * changes older than `changeRetentionDays` (default 30) unless a registered
+     * consumer updated within `maxFeedHoldDays` (default 7) still needs them.
+     */
+    changeFeed?: boolean | {
+        changeRetentionDays?: number;
+        maxFeedHoldDays?: number;
+    };
     notifications: ProductionNotificationOptions;
     managedDelivery: {
         adapter: ReportingManagedDeliveryAdapterV1;
@@ -273,3 +302,14 @@ export interface PostgresReliableReportingProductionServiceV1<TCtxMeta = Record<
  */
 export declare function createPostgresReliableReportingProductionService<TCtxMeta = Record<string, unknown>>(options: CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta>): Promise<PostgresReliableReportingProductionServiceV1<TCtxMeta>>;
 export * from './conformance';
+/**
+ * A scheduled maintenance pass completed but could not process some items
+ * (for example, a retention period whose objects could not be deleted). The
+ * pass resumes them next time; repeated reports need operator attention.
+ */
+export declare class ReportingMaintenancePartialFailureError extends Error {
+    readonly task: string;
+    readonly failedCount: number;
+    readonly failedIds: readonly string[];
+    constructor(task: string, failedCount: number, failedIds: readonly string[]);
+}

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

@@ -19,6 +19,7 @@ var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "defau
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var service_exports = {};
 __export(service_exports, {
+  ReportingMaintenancePartialFailureError: () => ReportingMaintenancePartialFailureError,
   createPostgresReliableReportingProductionService: () => createPostgresReliableReportingProductionService,
   createReliableReportingService: () => createReliableReportingService
 });
@@ -369,7 +370,9 @@ async function createPostgresReliableReportingProductionService(options) {
     managedDelivery: true,
     ...options.obligatedConsumers ? { obligatedConsumers: options.obligatedConsumers } : {},
     ...options.consumerMismatchEscalation ? { consumerMismatchEscalation: options.consumerMismatchEscalation } : {},
-    notificationActivityPort: notificationActivity.port
+    notificationActivityPort: notificationActivity.port,
+    ...options.rowStorage ? { rowStorage: options.rowStorage } : {},
+    ...options.changeFeed ? { changeFeed: true } : {}
   });
   const managedStore = new import_ledger.PostgresReportingManagedDeliveryStore(options.db, {
     ...options.managedDelivery.store,
@@ -385,12 +388,15 @@ async function createPostgresReliableReportingProductionService(options) {
   const core = createReliableReportingService(coreOptions);
   const migrations = Object.freeze([
     import_ledger.REPORTING_LEDGER_MIGRATION,
+    ...options.rowStorage ? [import_ledger.REPORTING_ROW_STORAGE_MIGRATION] : [],
+    ...options.changeFeed ? [import_ledger.REPORTING_LEDGER_CHANGES_MIGRATION] : [],
     import_ledger.REPORTING_MANAGED_DELIVERY_MIGRATION,
     ...notifications.migrations.all,
     ...notificationActivity.migrations.all,
     ...webhookActivity.migrations.all
   ]);
   await options.applyMigrations?.(migrations);
+  await coreStore.readyRowStorage();
   await notifications.probe();
   await notificationActivity.probe();
   await webhookActivity.probe();
@@ -500,6 +506,52 @@ async function createPostgresReliableReportingProductionService(options) {
     for (const result of pruneResults) {
       if (result.status === "rejected" && !signal.aborted) await reportAuxiliaryError(scheduler, result.reason);
     }
+    const ledgerMaintenance = [
+      ["snapshot sweep", (0, import_ledger.sweepExpiredReportingLedgerState)(options.db, 1e3)],
+      ["row upload sweep", coreStore.sweepRowWriteIntents({ limit: 100, signal })],
+      ...options.changeFeed ? [
+        [
+          "change-feed pruning",
+          coreStore.pruneChanges(
+            typeof options.changeFeed === "object" ? {
+              ...options.changeFeed.changeRetentionDays !== void 0 ? { changeRetentionDays: options.changeFeed.changeRetentionDays } : {},
+              ...options.changeFeed.maxFeedHoldDays !== void 0 ? { maxFeedHoldDays: options.changeFeed.maxFeedHoldDays } : {}
+            } : {}
+          )
+        ]
+      ] : [],
+      ...options.retention?.enabled ? [
+        [
+          "retention",
+          coreStore.retireExpiredPeriods({
+            statusRetentionDays: options.statusRetentionDays,
+            ...options.retention.recordRetentionDays !== void 0 ? { recordRetentionDays: options.retention.recordRetentionDays } : {},
+            limit: options.retention.limit ?? 100,
+            signal
+          })
+        ]
+      ] : []
+    ];
+    const maintenanceResults = await Promise.allSettled(ledgerMaintenance.map(([, task]) => task));
+    for (const [index, result] of maintenanceResults.entries()) {
+      const name = ledgerMaintenance[index][0];
+      if (result.status === "rejected") {
+        if (!signal.aborted) await reportAuxiliaryError(scheduler, result.reason);
+        continue;
+      }
+      const value = result.value;
+      const failed = Array.isArray(value?.failed) ? value.failed.length : typeof value?.failed === "number" ? value.failed : 0;
+      if (failed > 0 && !signal.aborted) {
+        await reportAuxiliaryError(
+          scheduler,
+          new ReportingMaintenancePartialFailureError(
+            name,
+            failed,
+            value?.failures?.length ? value.failures.map((entry) => `${entry.reporting_obligation_id} (${entry.cause})`) : Array.isArray(value?.failed) ? value.failed : []
+          )
+        );
+      }
+    }
     const accountIds = rotate(await deploymentWideAccountIds(coreStore), auxiliaryRotation);
     auxiliaryRotation += 1;
     for (const accountId of accountIds) {
@@ -1147,8 +1199,23 @@ function deepFreeze(value) {
   }
   return value;
 }
+class ReportingMaintenancePartialFailureError extends Error {
+  constructor(task, failedCount, failedIds) {
+    super(
+      `Reporting ${task} could not process ${failedCount} item(s)${failedIds.length ? `: ${failedIds.slice(0, 20).join(", ")}` : ""}`
+    );
+    this.task = task;
+    this.failedCount = failedCount;
+    this.failedIds = failedIds;
+    this.name = "ReportingMaintenancePartialFailureError";
+  }
+  task;
+  failedCount;
+  failedIds;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ReportingMaintenancePartialFailureError,
   createPostgresReliableReportingProductionService,
   createReliableReportingService,
   ...require('./conformance.js')

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

@@ -8,7 +8,10 @@ import {
 import {
   REPORTING_LEDGER_MIGRATION,
   REPORTING_MANAGED_DELIVERY_MIGRATION,
+  REPORTING_ROW_STORAGE_MIGRATION,
+  REPORTING_LEDGER_CHANGES_MIGRATION,
   PostgresReportingLedgerStore,
+  sweepExpiredReportingLedgerState,
   PostgresReportingManagedDeliveryStore,
   createPostgresReportingNotificationActivityRuntime,
   createPostgresReportingNotificationAttemptCheckpoint,
@@ -376,7 +379,9 @@ async function createPostgresReliableReportingProductionService(options) {
     managedDelivery: true,
     ...options.obligatedConsumers ? { obligatedConsumers: options.obligatedConsumers } : {},
     ...options.consumerMismatchEscalation ? { consumerMismatchEscalation: options.consumerMismatchEscalation } : {},
-    notificationActivityPort: notificationActivity.port
+    notificationActivityPort: notificationActivity.port,
+    ...options.rowStorage ? { rowStorage: options.rowStorage } : {},
+    ...options.changeFeed ? { changeFeed: true } : {}
   });
   const managedStore = new PostgresReportingManagedDeliveryStore(options.db, {
     ...options.managedDelivery.store,
@@ -392,12 +397,15 @@ async function createPostgresReliableReportingProductionService(options) {
   const core = createReliableReportingService(coreOptions);
   const migrations = Object.freeze([
     REPORTING_LEDGER_MIGRATION,
+    ...options.rowStorage ? [REPORTING_ROW_STORAGE_MIGRATION] : [],
+    ...options.changeFeed ? [REPORTING_LEDGER_CHANGES_MIGRATION] : [],
     REPORTING_MANAGED_DELIVERY_MIGRATION,
     ...notifications.migrations.all,
     ...notificationActivity.migrations.all,
     ...webhookActivity.migrations.all
   ]);
   await options.applyMigrations?.(migrations);
+  await coreStore.readyRowStorage();
   await notifications.probe();
   await notificationActivity.probe();
   await webhookActivity.probe();
@@ -507,6 +515,52 @@ async function createPostgresReliableReportingProductionService(options) {
     for (const result of pruneResults) {
       if (result.status === "rejected" && !signal.aborted) await reportAuxiliaryError(scheduler, result.reason);
     }
+    const ledgerMaintenance = [
+      ["snapshot sweep", sweepExpiredReportingLedgerState(options.db, 1e3)],
+      ["row upload sweep", coreStore.sweepRowWriteIntents({ limit: 100, signal })],
+      ...options.changeFeed ? [
+        [
+          "change-feed pruning",
+          coreStore.pruneChanges(
+            typeof options.changeFeed === "object" ? {
+              ...options.changeFeed.changeRetentionDays !== void 0 ? { changeRetentionDays: options.changeFeed.changeRetentionDays } : {},
+              ...options.changeFeed.maxFeedHoldDays !== void 0 ? { maxFeedHoldDays: options.changeFeed.maxFeedHoldDays } : {}
+            } : {}
+          )
+        ]
+      ] : [],
+      ...options.retention?.enabled ? [
+        [
+          "retention",
+          coreStore.retireExpiredPeriods({
+            statusRetentionDays: options.statusRetentionDays,
+            ...options.retention.recordRetentionDays !== void 0 ? { recordRetentionDays: options.retention.recordRetentionDays } : {},
+            limit: options.retention.limit ?? 100,
+            signal
+          })
+        ]
+      ] : []
+    ];
+    const maintenanceResults = await Promise.allSettled(ledgerMaintenance.map(([, task]) => task));
+    for (const [index, result] of maintenanceResults.entries()) {
+      const name = ledgerMaintenance[index][0];
+      if (result.status === "rejected") {
+        if (!signal.aborted) await reportAuxiliaryError(scheduler, result.reason);
+        continue;
+      }
+      const value = result.value;
+      const failed = Array.isArray(value?.failed) ? value.failed.length : typeof value?.failed === "number" ? value.failed : 0;
+      if (failed > 0 && !signal.aborted) {
+        await reportAuxiliaryError(
+          scheduler,
+          new ReportingMaintenancePartialFailureError(
+            name,
+            failed,
+            value?.failures?.length ? value.failures.map((entry) => `${entry.reporting_obligation_id} (${entry.cause})`) : Array.isArray(value?.failed) ? value.failed : []
+          )
+        );
+      }
+    }
     const accountIds = rotate(await deploymentWideAccountIds(coreStore), auxiliaryRotation);
     auxiliaryRotation += 1;
     for (const accountId of accountIds) {
@@ -1155,7 +1209,22 @@ function deepFreeze(value) {
   return value;
 }
 export * from "./conformance.mjs";
+class ReportingMaintenancePartialFailureError extends Error {
+  constructor(task, failedCount, failedIds) {
+    super(
+      `Reporting ${task} could not process ${failedCount} item(s)${failedIds.length ? `: ${failedIds.slice(0, 20).join(", ")}` : ""}`
+    );
+    this.task = task;
+    this.failedCount = failedCount;
+    this.failedIds = failedIds;
+    this.name = "ReportingMaintenancePartialFailureError";
+  }
+  task;
+  failedCount;
+  failedIds;
+}
 export {
+  ReportingMaintenancePartialFailureError,
   createPostgresReliableReportingProductionService,
   createReliableReportingService
 };

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-08T14:21:02.333Z"
+  "synced_at": "2026-10-09T05:22:53.040Z"
 }

package/dist/lib/signing/agent-resolver/fetch-helpers.js

@@ -118,7 +118,7 @@ function classifyDiscoveryFailure(error) {
   return { dns_error: "fetch_failed" };
 }
 function isPermanentDiscoveryFailure(detail) {
-  return detail.dns_error === "ssrf_refused" || detail.http_status !== void 0 && detail.http_status >= 400 && detail.http_status < 500;
+  return detail.dns_error === "ssrf_refused" || detail.http_status !== void 0 && detail.http_status >= 400 && detail.http_status < 500 && detail.http_status !== 408 && detail.http_status !== 429;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/lib/signing/agent-resolver/fetch-helpers.mjs

@@ -91,7 +91,7 @@ function classifyDiscoveryFailure(error) {
   return { dns_error: "fetch_failed" };
 }
 function isPermanentDiscoveryFailure(detail) {
-  return detail.dns_error === "ssrf_refused" || detail.http_status !== void 0 && detail.http_status >= 400 && detail.http_status < 500;
+  return detail.dns_error === "ssrf_refused" || detail.http_status !== void 0 && detail.http_status >= 400 && detail.http_status < 500 && detail.http_status !== 408 && detail.http_status !== 429;
 }
 export {
   DEFAULT_CONNECT_TIMEOUT_MS,

package/dist/lib/testing/storyboard/validations.d.mts

@@ -197,7 +197,7 @@ export interface UpstreamTrafficQueryResult {
  */
 export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
 /** Capability semver emitted in run summaries and used for advisory expiry. */
-export declare const RUNNER_CAPABILITY_VERSION = "15.3.0";
+export declare const RUNNER_CAPABILITY_VERSION = "15.5.0";
 /** True when a failed validation contributes to the owning step's grade. */
 export declare function validationFailsStep(result: ValidationResult): boolean;
 /**

package/dist/lib/testing/storyboard/validations.d.ts

@@ -197,7 +197,7 @@ export interface UpstreamTrafficQueryResult {
  */
 export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
 /** Capability semver emitted in run summaries and used for advisory expiry. */
-export declare const RUNNER_CAPABILITY_VERSION = "15.3.0";
+export declare const RUNNER_CAPABILITY_VERSION = "15.5.0";
 /** True when a failed validation contributes to the owning step's grade. */
 export declare function validationFailsStep(result: ValidationResult): boolean;
 /**

package/dist/lib/version.d.mts

@@ -1,7 +1,7 @@
 /**
  * AdCP SDK library version
  */
-export declare const LIBRARY_VERSION = "15.3.0";
+export declare const LIBRARY_VERSION = "15.5.0";
 /**
  * AdCP specification version this library is built for
  */
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
  * Full version information
  */
 export declare const VERSION_INFO: {
-    readonly library: "15.3.0";
+    readonly library: "15.5.0";
     readonly adcp: "3.2.3";
     readonly compatibleVersions: readonly ["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"];
-    readonly generatedAt: "2026-10-08T13:30:50.878Z";
+    readonly generatedAt: "2026-10-09T04:52:03.760Z";
 };
 /**
  * Get the AdCP specification version this library is built for

package/dist/lib/version.d.ts

@@ -1,7 +1,7 @@
 /**
  * AdCP SDK library version
  */
-export declare const LIBRARY_VERSION = "15.3.0";
+export declare const LIBRARY_VERSION = "15.5.0";
 /**
  * AdCP specification version this library is built for
  */
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
  * Full version information
  */
 export declare const VERSION_INFO: {
-    readonly library: "15.3.0";
+    readonly library: "15.5.0";
     readonly adcp: "3.2.3";
     readonly compatibleVersions: readonly ["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"];
-    readonly generatedAt: "2026-10-08T13:30:50.878Z";
+    readonly generatedAt: "2026-10-09T04:52:03.760Z";
 };
 /**
  * Get the AdCP specification version this library is built for

package/dist/lib/version.js

@@ -31,7 +31,7 @@ __export(version_exports, {
   toReleasePrecisionVersion: () => toReleasePrecisionVersion
 });
 module.exports = __toCommonJS(version_exports);
-const LIBRARY_VERSION = "15.3.0";
+const LIBRARY_VERSION = "15.5.0";
 const ADCP_VERSION = "3.2.3";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -97,10 +97,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.2.3"
 ];
 const VERSION_INFO = {
-  library: "15.3.0",
+  library: "15.5.0",
   adcp: "3.2.3",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-08T13:30:50.878Z"
+  generatedAt: "2026-10-09T04:52:03.760Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/dist/lib/version.mjs

@@ -1,4 +1,4 @@
-const LIBRARY_VERSION = "15.3.0";
+const LIBRARY_VERSION = "15.5.0";
 const ADCP_VERSION = "3.2.3";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -64,10 +64,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.2.3"
 ];
 const VERSION_INFO = {
-  library: "15.3.0",
+  library: "15.5.0",
   adcp: "3.2.3",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-08T13:30:50.878Z"
+  generatedAt: "2026-10-09T04:52:03.760Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/docs/README.md

@@ -23,7 +23,7 @@ list_products → buy_products → control_media_buy
 
 Use the [buyer quick start](./guides/BUYER-QUICKSTART-3.2.md). For the complete
 tool and type inventory, use [llms.txt](./llms.txt) and the
-[type summary](./TYPE-SUMMARY.md).
+[type summary](./TYPE-SUMMARY.md). For server-side callers that create a client per request, see [discovery caching and MCP session reuse](./guides/DISCOVERY-CACHE-AND-SESSION-REUSE.md).
 
 ## Upgrade from SDK 14.0