@adcp/sdk 15.4.0 → 15.6.0

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

@@ -0,0 +1,317 @@
+import { randomUUID } from "node:crypto";
+import {
+  DeleteObjectCommand,
+  GetBucketLifecycleConfigurationCommand,
+  GetBucketPolicyStatusCommand,
+  GetBucketVersioningCommand,
+  GetObjectCommand,
+  HeadBucketCommand,
+  HeadObjectCommand,
+  PutObjectCommand
+} from "@aws-sdk/client-s3";
+import { ReportingRowStoreError } from "../ledger/row-storage-errors.mjs";
+import {
+  assertReportingRowLocationKeys,
+  assertReportingRowReadBounds,
+  readReportingRowStream,
+  reportingRowClientMap,
+  reportingRowPrefixFilterOverlaps,
+  runReportingRowProviderOperation,
+  selectReportingRowClient
+} from "../ledger/row-storage-provider-io.mjs";
+const BUCKET = /^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/;
+const REGION = /^[a-z0-9][a-z0-9-]{0,30}[a-z0-9]$/;
+const VERSION_ID = /^[\x21\x23-\x7e]{1,1024}$/;
+function statusOf(error) {
+  const status = Number(error?.$metadata?.httpStatusCode);
+  return Number.isInteger(status) ? status : void 0;
+}
+function nameOf(error) {
+  const value = error?.name ?? error?.Code;
+  return typeof value === "string" ? value : "";
+}
+const isPreconditionFailed = (error) => statusOf(error) === 412 || nameOf(error) === "PreconditionFailed";
+const isConditionalConflict = (error) => statusOf(error) === 409 || nameOf(error) === "ConditionalRequestConflict";
+const isNotFound = (error) => statusOf(error) === 404 || ["NoSuchKey", "NotFound", "NoSuchVersion", "NoSuchBucket"].includes(nameOf(error));
+const isNotImplemented = (error) => statusOf(error) === 501 || nameOf(error) === "NotImplemented";
+const isForbidden = (error) => statusOf(error) === 401 || statusOf(error) === 403;
+const isRangeError = (error) => statusOf(error) === 416 || nameOf(error) === "InvalidRange";
+function versionOf(output) {
+  const id = output.VersionId;
+  if (typeof id !== "string" || id === "null" || !VERSION_ID.test(id)) {
+    throw new ReportingRowStoreError(
+      "UNSAFE_BINDING",
+      "store returned no object VersionId; S3 bucket versioning must be enabled so deletes are fenced to one write"
+    );
+  }
+  return id;
+}
+function selectorOf(nativeVersion) {
+  if (typeof nativeVersion !== "string" || nativeVersion === "null") return null;
+  return VERSION_ID.test(nativeVersion) ? { VersionId: nativeVersion } : null;
+}
+function servedVersion(output, selector) {
+  return output.VersionId === selector.VersionId;
+}
+function liveExpirationCovers(rule, prefix) {
+  if (rule.Status !== "Enabled") return false;
+  if (rule.Expiration?.Days === void 0 && rule.Expiration?.Date === void 0) return false;
+  if (rule.Filter?.Tag !== void 0 || (rule.Filter?.And?.Tags?.length ?? 0) > 0) return false;
+  const filter = rule.Filter?.Prefix ?? rule.Filter?.And?.Prefix ?? rule.Prefix;
+  return reportingRowPrefixFilterOverlaps(filter, prefix);
+}
+function createS3ReportingRowObjectProviderV1(options) {
+  if (!options || typeof options !== "object") {
+    throw new ReportingRowStoreError("INVALID_INPUT", "S3 row provider options are required");
+  }
+  const clients = reportingRowClientMap(options.clients);
+  const isClient = (value) => !!value && typeof value === "object" && typeof value.send === "function";
+  if (options.client !== void 0 && !isClient(options.client) || [...clients.values()].some((client) => !isClient(client)) || options.client === void 0 && clients.size === 0) {
+    throw new ReportingRowStoreError("INVALID_INPUT", "inject an official S3Client as client or clients");
+  }
+  const validateLocation = (location) => {
+    assertReportingRowLocationKeys(location, ["bucket"], ["region"]);
+    const bucket = location.bucket;
+    if (!BUCKET.test(bucket) || bucket.includes("..") || /^\d+\.\d+\.\d+\.\d+$/.test(bucket)) {
+      throw new ReportingRowStoreError("INVALID_INPUT", "S3 bucket name is invalid");
+    }
+    if (location.region !== void 0 && !REGION.test(location.region)) {
+      throw new ReportingRowStoreError("INVALID_INPUT", "S3 region is invalid");
+    }
+  };
+  const target = (input) => {
+    validateLocation(input.location);
+    return {
+      client: selectReportingRowClient(options.client, clients, input.credentialRef),
+      Bucket: input.location.bucket
+    };
+  };
+  const assertKey = (key) => {
+    if (typeof key !== "string" || key.length === 0 || Buffer.byteLength(key) > 1024) {
+      throw new ReportingRowStoreError("INVALID_INPUT", "object key is invalid");
+    }
+  };
+  async function putCreateOnly(client, params, signal) {
+    for (let attempt = 0; ; attempt++) {
+      try {
+        return await client.send(new PutObjectCommand({ ...params, IfNoneMatch: "*" }), { abortSignal: signal });
+      } catch (error) {
+        if (attempt === 0 && isConditionalConflict(error) && !signal.aborted) continue;
+        throw error;
+      }
+    }
+  }
+  async function assertVersioningEnabled(client, Bucket, signal) {
+    let status;
+    try {
+      status = (await client.send(new GetBucketVersioningCommand({ Bucket }), { abortSignal: signal })).Status;
+    } catch (error) {
+      if (isForbidden(error) || isNotImplemented(error)) {
+        throw new ReportingRowStoreError("UNSAFE_BINDING", "bucket versioning status cannot be verified");
+      }
+      throw error;
+    }
+    if (status !== "Enabled") {
+      throw new ReportingRowStoreError(
+        "UNSAFE_BINDING",
+        "S3 bucket versioning must be enabled so row object deletes are fenced to one write"
+      );
+    }
+  }
+  async function assertCreateOnlyEnforced(client, Bucket, prefix, signal) {
+    const Key = `${prefix}/.adcp-probe/${randomUUID()}`;
+    const written = [];
+    const put = async (body) => {
+      const output = await putCreateOnly(
+        client,
+        { Bucket, Key, Body: Buffer.from(body), ContentType: "application/x-ndjson", CacheControl: "no-store" },
+        signal
+      );
+      written.push(output);
+      versionOf(output);
+    };
+    try {
+      try {
+        await put('{"probe":1}\n');
+      } catch (error) {
+        if (isNotImplemented(error) || isPreconditionFailed(error)) {
+          throw new ReportingRowStoreError("UNSAFE_BINDING", "store does not support create-only writes");
+        }
+        throw error;
+      }
+      try {
+        await put('{"probe":2}\n');
+      } catch (error) {
+        if (isPreconditionFailed(error)) return;
+        if (isNotImplemented(error)) {
+          throw new ReportingRowStoreError("UNSAFE_BINDING", "store does not support create-only writes");
+        }
+        throw error;
+      }
+      throw new ReportingRowStoreError("UNSAFE_BINDING", "store ignores If-None-Match and replaces objects");
+    } finally {
+      const versionIds = written.map((output) => output.VersionId).filter((id) => !!id);
+      const deletes = versionIds.length > 0 ? versionIds.map((VersionId) => ({ VersionId })) : written.length ? [{}] : [];
+      for (const selector of deletes) {
+        if (signal.aborted) break;
+        await client.send(new DeleteObjectCommand({ Bucket, Key, ...selector }), { abortSignal: signal }).catch(() => void 0);
+      }
+    }
+  }
+  return {
+    name: "s3",
+    rangedReads: true,
+    validateLocation,
+    probe(input, context) {
+      return runReportingRowProviderOperation(context.signal, async () => {
+        const { client, Bucket } = target(input);
+        const signal = context.signal;
+        try {
+          await client.send(new HeadBucketCommand({ Bucket }), { abortSignal: signal });
+        } catch (error) {
+          if (isNotFound(error)) throw new ReportingRowStoreError("UNSAFE_BINDING", "bucket does not exist");
+          if (isForbidden(error)) throw new ReportingRowStoreError("UNSAFE_BINDING", "bucket is not accessible");
+          if (statusOf(error) === 301) {
+            throw new ReportingRowStoreError("UNSAFE_BINDING", "bucket is in a different region");
+          }
+          throw error;
+        }
+        if (input.location.region !== void 0) {
+          const configured = client.config?.region;
+          const region = typeof configured === "function" ? await configured() : configured;
+          if (region !== input.location.region) {
+            throw new ReportingRowStoreError("UNSAFE_BINDING", "client region does not match the binding");
+          }
+        }
+        const policy = await client.send(new GetBucketPolicyStatusCommand({ Bucket }), { abortSignal: signal }).catch(() => void 0);
+        if (policy?.PolicyStatus?.IsPublic === true) {
+          throw new ReportingRowStoreError("UNSAFE_BINDING", "bucket policy makes objects public");
+        }
+        let rules = [];
+        try {
+          const lifecycle = await client.send(new GetBucketLifecycleConfigurationCommand({ Bucket }), {
+            abortSignal: signal
+          });
+          rules = lifecycle.Rules ?? [];
+        } catch (error) {
+          if (isForbidden(error)) {
+            throw new ReportingRowStoreError("UNSAFE_BINDING", "bucket lifecycle cannot be read with this client");
+          }
+          if (!isNotFound(error) && !isNotImplemented(error) && nameOf(error) !== "NoSuchLifecycleConfiguration") {
+            throw error;
+          }
+        }
+        if (rules.some((rule) => liveExpirationCovers(rule, input.prefix))) {
+          throw new ReportingRowStoreError("UNSAFE_BINDING", "a bucket lifecycle rule can expire live row objects");
+        }
+        await assertVersioningEnabled(client, Bucket, signal);
+        await assertCreateOnlyEnforced(client, Bucket, input.prefix, signal);
+      });
+    },
+    putIfAbsent(input, context) {
+      return runReportingRowProviderOperation(context.signal, async () => {
+        const { client, Bucket } = target(input);
+        assertKey(input.key);
+        const bytes = Buffer.from(input.bytes);
+        try {
+          const output = await putCreateOnly(
+            client,
+            {
+              Bucket,
+              Key: input.key,
+              Body: bytes,
+              ContentLength: bytes.byteLength,
+              ContentType: input.contentType,
+              CacheControl: "no-store",
+              Metadata: { ...input.metadata }
+            },
+            context.signal
+          );
+          return { created: true, nativeVersion: versionOf(output) };
+        } catch (error) {
+          if (!isPreconditionFailed(error)) throw error;
+        }
+        const head = await client.send(new HeadObjectCommand({ Bucket, Key: input.key }), {
+          abortSignal: context.signal
+        });
+        return { created: false, nativeVersion: versionOf(head) };
+      });
+    },
+    get(input, context) {
+      return runReportingRowProviderOperation(context.signal, async () => {
+        const { client, Bucket } = target(input);
+        assertKey(input.key);
+        assertReportingRowReadBounds(input);
+        const selector = selectorOf(input.nativeVersion);
+        if (selector === null) return null;
+        const Key = input.key;
+        try {
+          if (input.range?.length === 0) {
+            const head = await client.send(new HeadObjectCommand({ Bucket, Key, ...selector }), {
+              abortSignal: context.signal
+            });
+            if (!servedVersion(head, selector)) return null;
+            if (input.range.offset > Number(head.ContentLength ?? 0)) {
+              throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "requested range exceeds the stored object");
+            }
+            return Buffer.alloc(0);
+          }
+          const output = await client.send(
+            new GetObjectCommand({
+              Bucket,
+              Key,
+              ...selector,
+              ...input.range ? { Range: `bytes=${input.range.offset}-${input.range.offset + input.range.length - 1}` } : {}
+            }),
+            { abortSignal: context.signal }
+          );
+          const body = output.Body;
+          if (!body || typeof body[Symbol.asyncIterator] !== "function") {
+            throw new ReportingRowStoreError("PROVIDER_UNAVAILABLE", "object body is not a stream");
+          }
+          if (!servedVersion(output, selector)) {
+            body.destroy?.();
+            return null;
+          }
+          if (typeof output.ContentLength === "number" && output.ContentLength > input.maxBytes) {
+            body.destroy?.();
+            throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "stored object exceeds its recorded size");
+          }
+          return await readReportingRowStream(body, input.maxBytes, context.signal);
+        } catch (error) {
+          if (isNotFound(error) || isPreconditionFailed(error)) return null;
+          if (statusOf(error) === 400 && nameOf(error) !== "InvalidRange") return null;
+          if (isRangeError(error)) {
+            throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "requested range exceeds the stored object");
+          }
+          throw error;
+        }
+      });
+    },
+    delete(input, context) {
+      return runReportingRowProviderOperation(context.signal, async () => {
+        const { client, Bucket } = target(input);
+        assertKey(input.key);
+        const selector = selectorOf(input.nativeVersion);
+        if (selector === null) return "absent";
+        const Key = input.key;
+        const signal = context.signal;
+        try {
+          const head = await client.send(new HeadObjectCommand({ Bucket, Key, ...selector }), { abortSignal: signal });
+          if (!servedVersion(head, selector)) return "absent";
+        } catch (error) {
+          if (isNotFound(error) || isPreconditionFailed(error)) return "absent";
+          if (statusOf(error) === 400 || statusOf(error) === 405) return "absent";
+          throw error;
+        }
+        await client.send(new DeleteObjectCommand({ Bucket, Key, VersionId: selector.VersionId }), {
+          abortSignal: signal
+        });
+        return "deleted";
+      });
+    }
+  };
+}
+export {
+  createS3ReportingRowObjectProviderV1
+};

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,37 @@ 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. 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;
+    };
+    /**
+     * 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 +304,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,37 @@ 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. 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;
+    };
+    /**
+     * 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 +304,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,53 @@ 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 } : {},
+            ...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 : []
+          )
+        );
+      }
+    }
     const accountIds = rotate(await deploymentWideAccountIds(coreStore), auxiliaryRotation);
     auxiliaryRotation += 1;
     for (const accountId of accountIds) {
@@ -1147,8 +1200,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,53 @@ 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 : []
+          )
+        );
+      }
+    }
     const accountIds = rotate(await deploymentWideAccountIds(coreStore), auxiliaryRotation);
     auxiliaryRotation += 1;
     for (const accountId of accountIds) {
@@ -1155,7 +1210,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
 };