@adcp/sdk 15.5.0 → 15.7.0

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

@@ -6,6 +6,7 @@ import type { ReportingDeliveryCapabilities, ReportingDeliveryOffering } from '.
 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 { type PostgresReportingWebhookActivityV1 } from '../webhook-activity.mjs';
+import { type ReportingChangeFeedMaintenanceOptionsV1, type ReportingLedgerMaintenanceTaskResultV1, 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. */
@@ -149,6 +150,29 @@ export interface CreateReliableReportingServiceOptionsV1<TCtxMeta = Record<strin
     /** Ledger metadata retention commitment advertised to buyers. */
     statusRetentionDays: number;
     subscribers?: CreateReportingProducerOptionsV1['subscribers'];
+    /**
+     * Opt in to scheduled ledger maintenance for a Core-only deployment on a
+     * `PostgresReportingLedgerStore`. `start()` runs it at most once per
+     * `intervalMilliseconds`; `runMaintenance()` runs it on demand for a host
+     * with its own scheduler. The production service does this itself and does
+     * not take this option.
+     *
+     * Always swept: expired cursor snapshots and checkpoints, and abandoned row
+     * uploads. `retention` and `changeFeed` have the same shape and meaning as
+     * on `createPostgresReliableReportingProductionService`. Retention uses
+     * this service's `statusRetentionDays`, so it can never retire a period
+     * earlier than the retention advertised to buyers. `changeFeed` requires the
+     * store to be built with `changeFeed: true`.
+     */
+    maintenance?: ReliableReportingMaintenanceOptionsV1;
+}
+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;
+    /** Change-feed pruning and consumer hold; see the production service's `changeFeed`. */
+    changeFeed?: ReportingChangeFeedMaintenanceOptionsV1;
 }
 export interface ReliableReportingSetupV1 {
     readonly component: 'reliable-reporting-core';
@@ -179,6 +203,14 @@ export interface ReliableReportingServiceV1<TCtxMeta = Record<string, unknown>>
         notReady: number;
         failed: number;
     }>;
+    /**
+     * Run one ledger-maintenance pass now and return each task's outcome. For
+     * hosts that run their own scheduler instead of `start()`. A task failure is
+     * reported in its result, not thrown. Requires the `maintenance` option.
+     */
+    runMaintenance(options?: {
+        signal?: AbortSignal;
+    }): Promise<ReportingLedgerMaintenanceTaskResultV1[]>;
     start(options: ReliableReportingSchedulerOptionsV1): void;
     stop(): Promise<void>;
 }
@@ -188,7 +220,7 @@ export interface ReliableReportingServiceV1<TCtxMeta = Record<string, unknown>>
  */
 export declare function createReliableReportingService<TCtxMeta = Record<string, unknown>>(options: CreateReliableReportingServiceOptionsV1<TCtxMeta>): ReliableReportingServiceV1<TCtxMeta>;
 type ProductionNotificationOptions = Omit<CreatePostgresPersistentNotificationRuntimeOptions, 'db' | 'publisherScope' | 'checkpointDeliveryAttempt' | 'supportedAccountEventTypes'>;
-export type CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta = Record<string, unknown>> = Omit<CreateReliableReportingServiceOptionsV1<TCtxMeta>, 'store' | 'subscribers'> & {
+export type CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta = Record<string, unknown>> = Omit<CreateReliableReportingServiceOptionsV1<TCtxMeta>, 'store' | 'subscribers' | 'maintenance'> & {
     db: ReportingPgPool;
     /** Stable, non-secret deployment namespace shared by reporting workers. */
     namespace: string;
@@ -207,13 +239,11 @@ export type CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta =
      * 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.
+     * and expired cursor snapshots are always swept. With `changeFeed`, a
+     * period is also held until every live registered feed consumer (updated
+     * within `changeFeed.maxFeedHoldDays`, default 7) has read its changes.
      */
-    retention?: {
-        enabled: true;
-        recordRetentionDays?: number;
-        limit?: number;
-    };
+    retention?: ReportingRetentionOptionsV1;
     /**
      * Maintain the host change feed (`changesAfter`, `getCurrentRevision`,
      * `listCurrentRevisions` on `stores.core`). Adds
@@ -221,10 +251,7 @@ export type CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta =
      * changes older than `changeRetentionDays` (default 30) unless a registered
      * consumer updated within `maxFeedHoldDays` (default 7) still needs them.
      */
-    changeFeed?: boolean | {
-        changeRetentionDays?: number;
-        maxFeedHoldDays?: number;
-    };
+    changeFeed?: ReportingChangeFeedMaintenanceOptionsV1;
     notifications: ProductionNotificationOptions;
     managedDelivery: {
         adapter: ReportingManagedDeliveryAdapterV1;
@@ -302,14 +329,4 @@ 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[]);
-}
+export { ReportingMaintenancePartialFailureError, type ReportingChangeFeedMaintenanceOptionsV1, type ReportingLedgerMaintenanceStoreV1, type ReportingLedgerMaintenanceTaskNameV1, type ReportingLedgerMaintenanceTaskResultV1, type ReportingRetentionOptionsV1, } from './maintenance.mjs';

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

@@ -6,6 +6,7 @@ import type { ReportingDeliveryCapabilities, ReportingDeliveryOffering } from '.
 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 { type PostgresReportingWebhookActivityV1 } from '../webhook-activity';
+import { type ReportingChangeFeedMaintenanceOptionsV1, type ReportingLedgerMaintenanceTaskResultV1, 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. */
@@ -149,6 +150,29 @@ export interface CreateReliableReportingServiceOptionsV1<TCtxMeta = Record<strin
     /** Ledger metadata retention commitment advertised to buyers. */
     statusRetentionDays: number;
     subscribers?: CreateReportingProducerOptionsV1['subscribers'];
+    /**
+     * Opt in to scheduled ledger maintenance for a Core-only deployment on a
+     * `PostgresReportingLedgerStore`. `start()` runs it at most once per
+     * `intervalMilliseconds`; `runMaintenance()` runs it on demand for a host
+     * with its own scheduler. The production service does this itself and does
+     * not take this option.
+     *
+     * Always swept: expired cursor snapshots and checkpoints, and abandoned row
+     * uploads. `retention` and `changeFeed` have the same shape and meaning as
+     * on `createPostgresReliableReportingProductionService`. Retention uses
+     * this service's `statusRetentionDays`, so it can never retire a period
+     * earlier than the retention advertised to buyers. `changeFeed` requires the
+     * store to be built with `changeFeed: true`.
+     */
+    maintenance?: ReliableReportingMaintenanceOptionsV1;
+}
+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;
+    /** Change-feed pruning and consumer hold; see the production service's `changeFeed`. */
+    changeFeed?: ReportingChangeFeedMaintenanceOptionsV1;
 }
 export interface ReliableReportingSetupV1 {
     readonly component: 'reliable-reporting-core';
@@ -179,6 +203,14 @@ export interface ReliableReportingServiceV1<TCtxMeta = Record<string, unknown>>
         notReady: number;
         failed: number;
     }>;
+    /**
+     * Run one ledger-maintenance pass now and return each task's outcome. For
+     * hosts that run their own scheduler instead of `start()`. A task failure is
+     * reported in its result, not thrown. Requires the `maintenance` option.
+     */
+    runMaintenance(options?: {
+        signal?: AbortSignal;
+    }): Promise<ReportingLedgerMaintenanceTaskResultV1[]>;
     start(options: ReliableReportingSchedulerOptionsV1): void;
     stop(): Promise<void>;
 }
@@ -188,7 +220,7 @@ export interface ReliableReportingServiceV1<TCtxMeta = Record<string, unknown>>
  */
 export declare function createReliableReportingService<TCtxMeta = Record<string, unknown>>(options: CreateReliableReportingServiceOptionsV1<TCtxMeta>): ReliableReportingServiceV1<TCtxMeta>;
 type ProductionNotificationOptions = Omit<CreatePostgresPersistentNotificationRuntimeOptions, 'db' | 'publisherScope' | 'checkpointDeliveryAttempt' | 'supportedAccountEventTypes'>;
-export type CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta = Record<string, unknown>> = Omit<CreateReliableReportingServiceOptionsV1<TCtxMeta>, 'store' | 'subscribers'> & {
+export type CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta = Record<string, unknown>> = Omit<CreateReliableReportingServiceOptionsV1<TCtxMeta>, 'store' | 'subscribers' | 'maintenance'> & {
     db: ReportingPgPool;
     /** Stable, non-secret deployment namespace shared by reporting workers. */
     namespace: string;
@@ -207,13 +239,11 @@ export type CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta =
      * 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.
+     * and expired cursor snapshots are always swept. With `changeFeed`, a
+     * period is also held until every live registered feed consumer (updated
+     * within `changeFeed.maxFeedHoldDays`, default 7) has read its changes.
      */
-    retention?: {
-        enabled: true;
-        recordRetentionDays?: number;
-        limit?: number;
-    };
+    retention?: ReportingRetentionOptionsV1;
     /**
      * Maintain the host change feed (`changesAfter`, `getCurrentRevision`,
      * `listCurrentRevisions` on `stores.core`). Adds
@@ -221,10 +251,7 @@ export type CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta =
      * changes older than `changeRetentionDays` (default 30) unless a registered
      * consumer updated within `maxFeedHoldDays` (default 7) still needs them.
      */
-    changeFeed?: boolean | {
-        changeRetentionDays?: number;
-        maxFeedHoldDays?: number;
-    };
+    changeFeed?: ReportingChangeFeedMaintenanceOptionsV1;
     notifications: ProductionNotificationOptions;
     managedDelivery: {
         adapter: ReportingManagedDeliveryAdapterV1;
@@ -302,14 +329,4 @@ 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[]);
-}
+export { ReportingMaintenancePartialFailureError, type ReportingChangeFeedMaintenanceOptionsV1, type ReportingLedgerMaintenanceStoreV1, type ReportingLedgerMaintenanceTaskNameV1, type ReportingLedgerMaintenanceTaskResultV1, type ReportingRetentionOptionsV1, } from './maintenance';

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

@@ -19,7 +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,
+  ReportingMaintenancePartialFailureError: () => import_maintenance2.ReportingMaintenancePartialFailureError,
   createPostgresReliableReportingProductionService: () => createPostgresReliableReportingProductionService,
   createReliableReportingService: () => createReliableReportingService
 });
@@ -31,11 +31,14 @@ var import_schemas = require('../../types/schemas.generated.js');
 var import_notification_subscriptions = require('../../server/notification-subscriptions/index.js');
 var import_ledger = require('../ledger/index.js');
 var import_webhook_activity = require('../webhook-activity.js');
+var import_maintenance = require('./maintenance.js');
 var import_schedule = require('../ledger/schedule.js');
 var import_source = require('../source/index.js');
 __reExport(service_exports, require('./conformance.js'), module.exports);
+var import_maintenance2 = require('./maintenance.js');
 const ADAPTER_SCOPE_KEY = "_adcp_reporting_adapter";
 const PRODUCTION_MANAGED_COMPOSITION = /* @__PURE__ */ Symbol("production-managed-reporting-composition");
+const DEFAULT_MAINTENANCE_INTERVAL_MILLISECONDS = 3e5;
 function createReliableReportingService(options) {
   const allowManagedDelivery = options[PRODUCTION_MANAGED_COMPOSITION] === true;
   const adapterEntries = Object.entries(options.adapters);
@@ -97,6 +100,42 @@ function createReliableReportingService(options) {
   if (hasConsumerStatus) assertConsumerStatusStore(options.store);
   const retentionDays = options.statusRetentionDays;
   positiveInteger(retentionDays, "statusRetentionDays");
+  const maintenance = options.maintenance;
+  let maintenanceStore;
+  let maintenanceIntervalMilliseconds = DEFAULT_MAINTENANCE_INTERVAL_MILLISECONDS;
+  if (maintenance !== void 0) {
+    if (maintenance === null || typeof maintenance !== "object") {
+      throw new TypeError("maintenance must be an options object");
+    }
+    const candidate = options.store;
+    for (const method of ["retireExpiredPeriods", "pruneChanges", "sweepRowWriteIntents"]) {
+      if (typeof candidate[method] !== "function") {
+        throw new TypeError(
+          `maintenance requires a PostgresReportingLedgerStore (or a store with ${method}); the configured store cannot run ledger maintenance`
+        );
+      }
+    }
+    maintenanceStore = candidate;
+    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"
+      );
+    }
+    if (maintenance.intervalMilliseconds !== void 0) {
+      positiveInteger(maintenance.intervalMilliseconds, "maintenance.intervalMilliseconds");
+      maintenanceIntervalMilliseconds = maintenance.intervalMilliseconds;
+    }
+    (0, import_maintenance.assertReportingLedgerMaintenanceOptions)(maintenance, retentionDays);
+  }
+  const runLedgerMaintenance = (signal, report) => (0, import_maintenance.runReportingLedgerMaintenance)({
+    store: maintenanceStore,
+    ...typeof maintenanceStore.sweepExpiredState === "function" ? { sweepSnapshots: (limit) => maintenanceStore.sweepExpiredState(limit) } : {},
+    statusRetentionDays: retentionDays,
+    retention: maintenance.retention,
+    changeFeed: maintenance.changeFeed,
+    signal,
+    ...report ? { report } : {}
+  });
   const capabilities = deepFreeze({
     supported: true,
     reliable_reporting_version: "1.0",
@@ -269,12 +308,26 @@ function createReliableReportingService(options) {
       });
       return { planned: planned.length, ...result };
     },
+    async runMaintenance(maintenanceOptions) {
+      if (maintenance === void 0) {
+        throw new TypeError("runMaintenance requires the maintenance option");
+      }
+      maintenanceOptions?.signal?.throwIfAborted();
+      return runLedgerMaintenance(maintenanceOptions?.signal);
+    },
     start(scheduler) {
       if (schedulerPromise) throw new Error("Reliable reporting scheduler is already running");
       positiveInteger(scheduler.intervalMilliseconds, "intervalMilliseconds");
       schedulerAbort = new AbortController();
       const signal = schedulerAbort.signal;
-      schedulerPromise = schedulerLoop(service, scheduler, signal, options.store).finally(() => {
+      const scheduledMaintenance = maintenance === void 0 ? void 0 : {
+        intervalMilliseconds: maintenanceIntervalMilliseconds,
+        run: () => runLedgerMaintenance(
+          signal,
+          (error) => reportSchedulerError(scheduler, signal, error, { phase: "maintenance" })
+        )
+      };
+      schedulerPromise = schedulerLoop(service, scheduler, signal, options.store, scheduledMaintenance).finally(() => {
         schedulerPromise = void 0;
         schedulerAbort = void 0;
       });
@@ -506,52 +559,15 @@ 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 : []
-          )
-        );
-      }
-    }
+    await (0, import_maintenance.runReportingLedgerMaintenance)({
+      store: coreStore,
+      sweepSnapshots: (limit) => (0, import_ledger.sweepExpiredReportingLedgerState)(options.db, limit),
+      statusRetentionDays: options.statusRetentionDays,
+      retention: options.retention,
+      changeFeed: options.changeFeed,
+      signal,
+      report: (error) => reportAuxiliaryError(scheduler, error)
+    });
     const accountIds = rotate(await deploymentWideAccountIds(coreStore), auxiliaryRotation);
     auxiliaryRotation += 1;
     for (const accountId of accountIds) {
@@ -677,8 +693,9 @@ function routeSource(sources, sourceScope) {
   if (!source) throw new TypeError("Reporting sourceScope has no installed adapter route");
   return source;
 }
-async function schedulerLoop(service, options, signal, store) {
+async function schedulerLoop(service, options, signal, store, maintenance) {
   let rotation = 0;
+  let lastMaintenanceAt;
   while (!signal.aborted) {
     let accountIds = [];
     try {
@@ -715,6 +732,14 @@ async function schedulerLoop(service, options, signal, store) {
         await reportSchedulerError(options, signal, error, { phase: "cycle", accountId });
       }
     }
+    if (maintenance && !signal.aborted && (lastMaintenanceAt === void 0 || Date.now() - lastMaintenanceAt >= maintenance.intervalMilliseconds)) {
+      lastMaintenanceAt = Date.now();
+      try {
+        await maintenance.run();
+      } catch (error) {
+        await reportSchedulerError(options, signal, error, { phase: "maintenance" });
+      }
+    }
     if (!signal.aborted) await abortableDelay(options.intervalMilliseconds, signal);
   }
 }
@@ -731,7 +756,7 @@ async function reportSchedulerError(options, signal, error, site) {
   warnSchedulerFailure(options, site, error);
 }
 function warnSchedulerFailure(options, site, error, observerError) {
-  const where = site.phase === "roster" ? "could not resolve its account roster, so this pass ran no tenants" : site.accountId === void 0 ? "deployment-wide cycle failed; the scheduler continues" : `cycle failed for account ${site.accountId}; later tenants continue`;
+  const where = site.phase === "roster" ? "could not resolve its account roster, so this pass ran no tenants" : site.phase === "maintenance" ? "ledger maintenance failed; the scheduler continues" : site.accountId === void 0 ? "deployment-wide cycle failed; the scheduler continues" : `cycle failed for account ${site.accountId}; later tenants continue`;
   const observed = observerError === void 0 ? "" : ` (the configured onError also threw: ${safeMessage(observerError)})`;
   const message = `[adcp/reporting] scheduler ${where}: ${safeMessage(error)}${observed}`;
   const logger = options.logger;
@@ -1199,20 +1224,6 @@ 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,

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

@@ -30,6 +30,10 @@ import {
   createPostgresReportingWebhookActivityV1,
   projectListAccountsReportingWebhookActivityV1
 } from "../webhook-activity.mjs";
+import {
+  assertReportingLedgerMaintenanceOptions,
+  runReportingLedgerMaintenance
+} from "./maintenance.mjs";
 import { assertReportingCalendarDaySource, reportingCalendarDayOrigin } from "../ledger/schedule.mjs";
 import {
   ReportingCoverageConstituentIdentityV1Schema,
@@ -45,6 +49,7 @@ import {
 } from "../source/index.mjs";
 const ADAPTER_SCOPE_KEY = "_adcp_reporting_adapter";
 const PRODUCTION_MANAGED_COMPOSITION = /* @__PURE__ */ Symbol("production-managed-reporting-composition");
+const DEFAULT_MAINTENANCE_INTERVAL_MILLISECONDS = 3e5;
 function createReliableReportingService(options) {
   const allowManagedDelivery = options[PRODUCTION_MANAGED_COMPOSITION] === true;
   const adapterEntries = Object.entries(options.adapters);
@@ -106,6 +111,42 @@ function createReliableReportingService(options) {
   if (hasConsumerStatus) assertConsumerStatusStore(options.store);
   const retentionDays = options.statusRetentionDays;
   positiveInteger(retentionDays, "statusRetentionDays");
+  const maintenance = options.maintenance;
+  let maintenanceStore;
+  let maintenanceIntervalMilliseconds = DEFAULT_MAINTENANCE_INTERVAL_MILLISECONDS;
+  if (maintenance !== void 0) {
+    if (maintenance === null || typeof maintenance !== "object") {
+      throw new TypeError("maintenance must be an options object");
+    }
+    const candidate = options.store;
+    for (const method of ["retireExpiredPeriods", "pruneChanges", "sweepRowWriteIntents"]) {
+      if (typeof candidate[method] !== "function") {
+        throw new TypeError(
+          `maintenance requires a PostgresReportingLedgerStore (or a store with ${method}); the configured store cannot run ledger maintenance`
+        );
+      }
+    }
+    maintenanceStore = candidate;
+    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"
+      );
+    }
+    if (maintenance.intervalMilliseconds !== void 0) {
+      positiveInteger(maintenance.intervalMilliseconds, "maintenance.intervalMilliseconds");
+      maintenanceIntervalMilliseconds = maintenance.intervalMilliseconds;
+    }
+    assertReportingLedgerMaintenanceOptions(maintenance, retentionDays);
+  }
+  const runLedgerMaintenance = (signal, report) => runReportingLedgerMaintenance({
+    store: maintenanceStore,
+    ...typeof maintenanceStore.sweepExpiredState === "function" ? { sweepSnapshots: (limit) => maintenanceStore.sweepExpiredState(limit) } : {},
+    statusRetentionDays: retentionDays,
+    retention: maintenance.retention,
+    changeFeed: maintenance.changeFeed,
+    signal,
+    ...report ? { report } : {}
+  });
   const capabilities = deepFreeze({
     supported: true,
     reliable_reporting_version: "1.0",
@@ -278,12 +319,26 @@ function createReliableReportingService(options) {
       });
       return { planned: planned.length, ...result };
     },
+    async runMaintenance(maintenanceOptions) {
+      if (maintenance === void 0) {
+        throw new TypeError("runMaintenance requires the maintenance option");
+      }
+      maintenanceOptions?.signal?.throwIfAborted();
+      return runLedgerMaintenance(maintenanceOptions?.signal);
+    },
     start(scheduler) {
       if (schedulerPromise) throw new Error("Reliable reporting scheduler is already running");
       positiveInteger(scheduler.intervalMilliseconds, "intervalMilliseconds");
       schedulerAbort = new AbortController();
       const signal = schedulerAbort.signal;
-      schedulerPromise = schedulerLoop(service, scheduler, signal, options.store).finally(() => {
+      const scheduledMaintenance = maintenance === void 0 ? void 0 : {
+        intervalMilliseconds: maintenanceIntervalMilliseconds,
+        run: () => runLedgerMaintenance(
+          signal,
+          (error) => reportSchedulerError(scheduler, signal, error, { phase: "maintenance" })
+        )
+      };
+      schedulerPromise = schedulerLoop(service, scheduler, signal, options.store, scheduledMaintenance).finally(() => {
         schedulerPromise = void 0;
         schedulerAbort = void 0;
       });
@@ -515,52 +570,15 @@ 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 : []
-          )
-        );
-      }
-    }
+    await runReportingLedgerMaintenance({
+      store: coreStore,
+      sweepSnapshots: (limit) => sweepExpiredReportingLedgerState(options.db, limit),
+      statusRetentionDays: options.statusRetentionDays,
+      retention: options.retention,
+      changeFeed: options.changeFeed,
+      signal,
+      report: (error) => reportAuxiliaryError(scheduler, error)
+    });
     const accountIds = rotate(await deploymentWideAccountIds(coreStore), auxiliaryRotation);
     auxiliaryRotation += 1;
     for (const accountId of accountIds) {
@@ -686,8 +704,9 @@ function routeSource(sources, sourceScope) {
   if (!source) throw new TypeError("Reporting sourceScope has no installed adapter route");
   return source;
 }
-async function schedulerLoop(service, options, signal, store) {
+async function schedulerLoop(service, options, signal, store, maintenance) {
   let rotation = 0;
+  let lastMaintenanceAt;
   while (!signal.aborted) {
     let accountIds = [];
     try {
@@ -724,6 +743,14 @@ async function schedulerLoop(service, options, signal, store) {
         await reportSchedulerError(options, signal, error, { phase: "cycle", accountId });
       }
     }
+    if (maintenance && !signal.aborted && (lastMaintenanceAt === void 0 || Date.now() - lastMaintenanceAt >= maintenance.intervalMilliseconds)) {
+      lastMaintenanceAt = Date.now();
+      try {
+        await maintenance.run();
+      } catch (error) {
+        await reportSchedulerError(options, signal, error, { phase: "maintenance" });
+      }
+    }
     if (!signal.aborted) await abortableDelay(options.intervalMilliseconds, signal);
   }
 }
@@ -740,7 +767,7 @@ async function reportSchedulerError(options, signal, error, site) {
   warnSchedulerFailure(options, site, error);
 }
 function warnSchedulerFailure(options, site, error, observerError) {
-  const where = site.phase === "roster" ? "could not resolve its account roster, so this pass ran no tenants" : site.accountId === void 0 ? "deployment-wide cycle failed; the scheduler continues" : `cycle failed for account ${site.accountId}; later tenants continue`;
+  const where = site.phase === "roster" ? "could not resolve its account roster, so this pass ran no tenants" : site.phase === "maintenance" ? "ledger maintenance failed; the scheduler continues" : site.accountId === void 0 ? "deployment-wide cycle failed; the scheduler continues" : `cycle failed for account ${site.accountId}; later tenants continue`;
   const observed = observerError === void 0 ? "" : ` (the configured onError also threw: ${safeMessage(observerError)})`;
   const message = `[adcp/reporting] scheduler ${where}: ${safeMessage(error)}${observed}`;
   const logger = options.logger;
@@ -1209,20 +1236,9 @@ 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;
-}
+import {
+  ReportingMaintenancePartialFailureError
+} from "./maintenance.mjs";
 export {
   ReportingMaintenancePartialFailureError,
   createPostgresReliableReportingProductionService,