@adcp/sdk 15.6.0 → 15.7.0

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,53 +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 } : {},
-            ...typeof options.changeFeed === "object" && options.changeFeed.maxFeedHoldDays !== void 0 ? { maxFeedHoldDays: options.changeFeed.maxFeedHoldDays } : {},
-            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) {
@@ -687,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 {
@@ -725,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);
   }
 }
@@ -741,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;
@@ -1210,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,

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

@@ -0,0 +1,91 @@
+import type { PostgresReportingLedgerStore } from '../ledger/index.mjs';
+/**
+ * Period-aligned retention. Whole periods are retired once
+ * `max(statusRetentionDays, recordRetentionDays)` has elapsed since both the
+ * period end and its latest publication. `statusRetentionDays` always comes
+ * from the service, so retention can never disagree with the commitment the
+ * service advertises to buyers.
+ */
+export interface ReportingRetentionOptionsV1 {
+    enabled: true;
+    recordRetentionDays?: number;
+    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'>;
+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']>>;
+}
+export type ReportingLedgerMaintenanceTaskNameV1 = keyof ReportingLedgerMaintenanceTaskOutcomesV1;
+/**
+ * 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[]);
+}
+/**
+ * Outcome of one maintenance task. A task that resolved but could not process
+ * some items (a retention period whose objects would not delete, an upload that
+ * would not sweep) is `completed` with `partialFailure` set; the pass resumes
+ * those items next time.
+ */
+export type ReportingLedgerMaintenanceTaskResultV1 = {
+    [Task in ReportingLedgerMaintenanceTaskNameV1]: {
+        readonly task: Task;
+        readonly status: 'completed';
+        readonly result: ReportingLedgerMaintenanceTaskOutcomesV1[Task];
+        readonly partialFailure?: ReportingMaintenancePartialFailureError;
+    } | {
+        readonly task: Task;
+        readonly status: 'failed';
+        readonly error: unknown;
+    };
+}[ReportingLedgerMaintenanceTaskNameV1];
+export interface RunReportingLedgerMaintenanceInputV1 {
+    store: ReportingLedgerMaintenanceStoreV1;
+    /**
+     * Expired cursor snapshot and checkpoint sweep. Omitted when the caller has
+     * no way to reach the database, in which case that task is not run.
+     */
+    sweepSnapshots?: (limit: number) => Promise<ReportingLedgerMaintenanceTaskOutcomesV1['snapshot sweep']>;
+    statusRetentionDays: number;
+    retention?: ReportingRetentionOptionsV1 | undefined;
+    changeFeed?: ReportingChangeFeedMaintenanceOptionsV1 | undefined;
+    signal?: AbortSignal | undefined;
+    /**
+     * Called, in task order and awaited, for every task that rejected or
+     * partially failed, unless `signal` has aborted (an abort is shutdown, not a
+     * fault).
+     */
+    report?: (error: unknown) => Promise<void>;
+}
+/**
+ * The single ledger-maintenance pass shared by the Core service and the
+ * production service, so partial-failure surfacing, the `maxFeedHoldDays` that
+ * retention honours, per-task limits and abort handling cannot drift between
+ * them. Tasks start together, in a fixed order, and are isolated: one task's
+ * failure never prevents another from running.
+ */
+export declare function runReportingLedgerMaintenance(input: RunReportingLedgerMaintenanceInputV1): Promise<ReportingLedgerMaintenanceTaskResultV1[]>;
+/**
+ * Fail fast on maintenance options the store would otherwise reject on every
+ * pass. Mirrors the checks `retireExpiredPeriods` and `pruneChanges` apply.
+ */
+export declare function assertReportingLedgerMaintenanceOptions(input: {
+    retention?: ReportingRetentionOptionsV1 | undefined;
+    changeFeed?: ReportingChangeFeedMaintenanceOptionsV1 | undefined;
+}, statusRetentionDays: number): void;
+export {};

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

@@ -0,0 +1,91 @@
+import type { PostgresReportingLedgerStore } from '../ledger';
+/**
+ * Period-aligned retention. Whole periods are retired once
+ * `max(statusRetentionDays, recordRetentionDays)` has elapsed since both the
+ * period end and its latest publication. `statusRetentionDays` always comes
+ * from the service, so retention can never disagree with the commitment the
+ * service advertises to buyers.
+ */
+export interface ReportingRetentionOptionsV1 {
+    enabled: true;
+    recordRetentionDays?: number;
+    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'>;
+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']>>;
+}
+export type ReportingLedgerMaintenanceTaskNameV1 = keyof ReportingLedgerMaintenanceTaskOutcomesV1;
+/**
+ * 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[]);
+}
+/**
+ * Outcome of one maintenance task. A task that resolved but could not process
+ * some items (a retention period whose objects would not delete, an upload that
+ * would not sweep) is `completed` with `partialFailure` set; the pass resumes
+ * those items next time.
+ */
+export type ReportingLedgerMaintenanceTaskResultV1 = {
+    [Task in ReportingLedgerMaintenanceTaskNameV1]: {
+        readonly task: Task;
+        readonly status: 'completed';
+        readonly result: ReportingLedgerMaintenanceTaskOutcomesV1[Task];
+        readonly partialFailure?: ReportingMaintenancePartialFailureError;
+    } | {
+        readonly task: Task;
+        readonly status: 'failed';
+        readonly error: unknown;
+    };
+}[ReportingLedgerMaintenanceTaskNameV1];
+export interface RunReportingLedgerMaintenanceInputV1 {
+    store: ReportingLedgerMaintenanceStoreV1;
+    /**
+     * Expired cursor snapshot and checkpoint sweep. Omitted when the caller has
+     * no way to reach the database, in which case that task is not run.
+     */
+    sweepSnapshots?: (limit: number) => Promise<ReportingLedgerMaintenanceTaskOutcomesV1['snapshot sweep']>;
+    statusRetentionDays: number;
+    retention?: ReportingRetentionOptionsV1 | undefined;
+    changeFeed?: ReportingChangeFeedMaintenanceOptionsV1 | undefined;
+    signal?: AbortSignal | undefined;
+    /**
+     * Called, in task order and awaited, for every task that rejected or
+     * partially failed, unless `signal` has aborted (an abort is shutdown, not a
+     * fault).
+     */
+    report?: (error: unknown) => Promise<void>;
+}
+/**
+ * The single ledger-maintenance pass shared by the Core service and the
+ * production service, so partial-failure surfacing, the `maxFeedHoldDays` that
+ * retention honours, per-task limits and abort handling cannot drift between
+ * them. Tasks start together, in a fixed order, and are isolated: one task's
+ * failure never prevents another from running.
+ */
+export declare function runReportingLedgerMaintenance(input: RunReportingLedgerMaintenanceInputV1): Promise<ReportingLedgerMaintenanceTaskResultV1[]>;
+/**
+ * Fail fast on maintenance options the store would otherwise reject on every
+ * pass. Mirrors the checks `retireExpiredPeriods` and `pruneChanges` apply.
+ */
+export declare function assertReportingLedgerMaintenanceOptions(input: {
+    retention?: ReportingRetentionOptionsV1 | undefined;
+    changeFeed?: ReportingChangeFeedMaintenanceOptionsV1 | undefined;
+}, statusRetentionDays: number): void;
+export {};

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

@@ -0,0 +1,140 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var maintenance_exports = {};
+__export(maintenance_exports, {
+  ReportingMaintenancePartialFailureError: () => ReportingMaintenancePartialFailureError,
+  assertReportingLedgerMaintenanceOptions: () => assertReportingLedgerMaintenanceOptions,
+  runReportingLedgerMaintenance: () => runReportingLedgerMaintenance
+});
+module.exports = __toCommonJS(maintenance_exports);
+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;
+}
+async function runReportingLedgerMaintenance(input) {
+  const { store, signal, changeFeed, retention } = input;
+  const start = (name, run) => {
+    try {
+      return [name, run()];
+    } catch (error) {
+      return [name, Promise.reject(error)];
+    }
+  };
+  const tasks = [
+    ...input.sweepSnapshots ? [start("snapshot sweep", () => input.sweepSnapshots(1e3))] : [],
+    start("row upload sweep", () => store.sweepRowWriteIntents({ limit: 100, ...signal ? { signal } : {} })),
+    ...changeFeed ? [
+      start(
+        "change-feed pruning",
+        () => store.pruneChanges(
+          typeof changeFeed === "object" ? {
+            ...changeFeed.changeRetentionDays !== void 0 ? { changeRetentionDays: changeFeed.changeRetentionDays } : {},
+            ...changeFeed.maxFeedHoldDays !== void 0 ? { maxFeedHoldDays: changeFeed.maxFeedHoldDays } : {}
+          } : {}
+        )
+      )
+    ] : [],
+    ...retention?.enabled ? [
+      start(
+        "retention",
+        () => store.retireExpiredPeriods({
+          statusRetentionDays: input.statusRetentionDays,
+          ...retention.recordRetentionDays !== void 0 ? { recordRetentionDays: retention.recordRetentionDays } : {},
+          ...typeof changeFeed === "object" && changeFeed.maxFeedHoldDays !== void 0 ? { maxFeedHoldDays: changeFeed.maxFeedHoldDays } : {},
+          limit: retention.limit ?? 100,
+          ...signal ? { signal } : {}
+        })
+      )
+    ] : []
+  ];
+  const settled = await Promise.allSettled(tasks.map(([, task]) => task));
+  const results = [];
+  for (const [index, outcome] of settled.entries()) {
+    const name = tasks[index][0];
+    if (outcome.status === "rejected") {
+      if (!signal?.aborted) await input.report?.(outcome.reason);
+      results.push({ task: name, status: "failed", error: outcome.reason });
+      continue;
+    }
+    const value = outcome.value;
+    const failed = Array.isArray(value?.failed) ? value.failed.length : typeof value?.failed === "number" ? value.failed : 0;
+    let partialFailure;
+    if (failed > 0) {
+      partialFailure = new ReportingMaintenancePartialFailureError(
+        name,
+        failed,
+        value?.failures?.length ? value.failures.map((entry) => `${entry.reporting_obligation_id} (${entry.cause})`) : Array.isArray(value?.failed) ? value.failed : []
+      );
+      if (!signal?.aborted) await input.report?.(partialFailure);
+    }
+    results.push({
+      task: name,
+      status: "completed",
+      result: outcome.value,
+      ...partialFailure ? { partialFailure } : {}
+    });
+  }
+  return results;
+}
+function assertReportingLedgerMaintenanceOptions(input, statusRetentionDays) {
+  const positive = (value, field) => {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+      throw new TypeError(`${field} must be a positive safe integer`);
+    }
+  };
+  const { retention, changeFeed } = input;
+  if (retention !== void 0) {
+    if (retention === null || typeof retention !== "object" || retention.enabled !== true) {
+      throw new TypeError("maintenance.retention must be { enabled: true, ... }");
+    }
+    if (retention.recordRetentionDays !== void 0) {
+      positive(retention.recordRetentionDays, "maintenance.retention.recordRetentionDays");
+      if (retention.recordRetentionDays < statusRetentionDays) {
+        throw new RangeError(
+          "maintenance.retention.recordRetentionDays must be no shorter than statusRetentionDays, the retention advertised to buyers"
+        );
+      }
+    }
+    if (retention.limit !== void 0) positive(retention.limit, "maintenance.retention.limit");
+  }
+  if (typeof changeFeed === "object" && changeFeed !== null) {
+    if (changeFeed.changeRetentionDays !== void 0) {
+      positive(changeFeed.changeRetentionDays, "maintenance.changeFeed.changeRetentionDays");
+    }
+    if (changeFeed.maxFeedHoldDays !== void 0) {
+      positive(changeFeed.maxFeedHoldDays, "maintenance.changeFeed.maxFeedHoldDays");
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ReportingMaintenancePartialFailureError,
+  assertReportingLedgerMaintenanceOptions,
+  runReportingLedgerMaintenance
+});

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

@@ -0,0 +1,114 @@
+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;
+}
+async function runReportingLedgerMaintenance(input) {
+  const { store, signal, changeFeed, retention } = input;
+  const start = (name, run) => {
+    try {
+      return [name, run()];
+    } catch (error) {
+      return [name, Promise.reject(error)];
+    }
+  };
+  const tasks = [
+    ...input.sweepSnapshots ? [start("snapshot sweep", () => input.sweepSnapshots(1e3))] : [],
+    start("row upload sweep", () => store.sweepRowWriteIntents({ limit: 100, ...signal ? { signal } : {} })),
+    ...changeFeed ? [
+      start(
+        "change-feed pruning",
+        () => store.pruneChanges(
+          typeof changeFeed === "object" ? {
+            ...changeFeed.changeRetentionDays !== void 0 ? { changeRetentionDays: changeFeed.changeRetentionDays } : {},
+            ...changeFeed.maxFeedHoldDays !== void 0 ? { maxFeedHoldDays: changeFeed.maxFeedHoldDays } : {}
+          } : {}
+        )
+      )
+    ] : [],
+    ...retention?.enabled ? [
+      start(
+        "retention",
+        () => store.retireExpiredPeriods({
+          statusRetentionDays: input.statusRetentionDays,
+          ...retention.recordRetentionDays !== void 0 ? { recordRetentionDays: retention.recordRetentionDays } : {},
+          ...typeof changeFeed === "object" && changeFeed.maxFeedHoldDays !== void 0 ? { maxFeedHoldDays: changeFeed.maxFeedHoldDays } : {},
+          limit: retention.limit ?? 100,
+          ...signal ? { signal } : {}
+        })
+      )
+    ] : []
+  ];
+  const settled = await Promise.allSettled(tasks.map(([, task]) => task));
+  const results = [];
+  for (const [index, outcome] of settled.entries()) {
+    const name = tasks[index][0];
+    if (outcome.status === "rejected") {
+      if (!signal?.aborted) await input.report?.(outcome.reason);
+      results.push({ task: name, status: "failed", error: outcome.reason });
+      continue;
+    }
+    const value = outcome.value;
+    const failed = Array.isArray(value?.failed) ? value.failed.length : typeof value?.failed === "number" ? value.failed : 0;
+    let partialFailure;
+    if (failed > 0) {
+      partialFailure = new ReportingMaintenancePartialFailureError(
+        name,
+        failed,
+        value?.failures?.length ? value.failures.map((entry) => `${entry.reporting_obligation_id} (${entry.cause})`) : Array.isArray(value?.failed) ? value.failed : []
+      );
+      if (!signal?.aborted) await input.report?.(partialFailure);
+    }
+    results.push({
+      task: name,
+      status: "completed",
+      result: outcome.value,
+      ...partialFailure ? { partialFailure } : {}
+    });
+  }
+  return results;
+}
+function assertReportingLedgerMaintenanceOptions(input, statusRetentionDays) {
+  const positive = (value, field) => {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+      throw new TypeError(`${field} must be a positive safe integer`);
+    }
+  };
+  const { retention, changeFeed } = input;
+  if (retention !== void 0) {
+    if (retention === null || typeof retention !== "object" || retention.enabled !== true) {
+      throw new TypeError("maintenance.retention must be { enabled: true, ... }");
+    }
+    if (retention.recordRetentionDays !== void 0) {
+      positive(retention.recordRetentionDays, "maintenance.retention.recordRetentionDays");
+      if (retention.recordRetentionDays < statusRetentionDays) {
+        throw new RangeError(
+          "maintenance.retention.recordRetentionDays must be no shorter than statusRetentionDays, the retention advertised to buyers"
+        );
+      }
+    }
+    if (retention.limit !== void 0) positive(retention.limit, "maintenance.retention.limit");
+  }
+  if (typeof changeFeed === "object" && changeFeed !== null) {
+    if (changeFeed.changeRetentionDays !== void 0) {
+      positive(changeFeed.changeRetentionDays, "maintenance.changeFeed.changeRetentionDays");
+    }
+    if (changeFeed.maxFeedHoldDays !== void 0) {
+      positive(changeFeed.maxFeedHoldDays, "maintenance.changeFeed.maxFeedHoldDays");
+    }
+  }
+}
+export {
+  ReportingMaintenancePartialFailureError,
+  assertReportingLedgerMaintenanceOptions,
+  runReportingLedgerMaintenance
+};

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-09T12:16:02.843Z"
+  "synced_at": "2026-10-09T23:50:25.104Z"
 }

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.6.0";
+export declare const RUNNER_CAPABILITY_VERSION = "15.7.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.6.0";
+export declare const RUNNER_CAPABILITY_VERSION = "15.7.0";
 /** True when a failed validation contributes to the owning step's grade. */
 export declare function validationFailsStep(result: ValidationResult): boolean;
 /**