@adcp/sdk 15.5.0 → 15.7.0

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

@@ -0,0 +1,341 @@
+import { createHash } from "crypto";
+import { promises as fs } from "fs";
+import { tmpdir } from "os";
+import * as path from "path";
+const REPORTING_WAREHOUSE_SINK_MIGRATION = `
+CREATE TABLE IF NOT EXISTS adcp_reporting_warehouse_sinks (
+  sink_name TEXT PRIMARY KEY CHECK (sink_name ~ '^[A-Za-z0-9_.:-]{1,128}$'),
+  committed_cursor TEXT,
+  planned_from_cursor TEXT,
+  planned_to_cursor TEXT,
+  planned_revisions JSONB,
+  planned_rows_attempt INTEGER NOT NULL DEFAULT 0 CHECK (planned_rows_attempt >= 0),
+  planned_revisions_attempt INTEGER NOT NULL DEFAULT 0 CHECK (planned_revisions_attempt >= 0),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
+  CHECK ((planned_to_cursor IS NULL) = (planned_revisions IS NULL))
+);
+`.trim();
+const PROJECT = /^[a-z][a-z0-9-]{4,61}[a-z0-9]$/;
+const DATASET_OR_TABLE = /^[A-Za-z_][A-Za-z0-9_]{0,1023}$/;
+const NAME = /^[A-Za-z0-9_.:-]{1,128}$/;
+function createBigQueryReportingWarehouseSinkV1(options) {
+  if (!NAME.test(options.name)) throw new TypeError("Warehouse sink name must be a bounded non-secret identifier");
+  if (options.projectId !== void 0 && !PROJECT.test(options.projectId)) {
+    throw new TypeError("BigQuery projectId is invalid");
+  }
+  for (const [label, value] of [
+    ["datasetId", options.datasetId],
+    ["rowsTableId", options.rowsTableId],
+    ["revisionsTableId", options.revisionsTableId]
+  ]) {
+    if (!DATASET_OR_TABLE.test(value)) throw new TypeError(`BigQuery ${label} is invalid`);
+  }
+  const loadTimeout = options.loadTimeoutMilliseconds ?? 6e5;
+  if (!Number.isSafeInteger(loadTimeout) || loadTimeout < 1e3 || loadTimeout > 6 * 36e5) {
+    throw new RangeError("loadTimeoutMilliseconds must be between 1 second and 6 hours");
+  }
+  const maxRevisions = options.maxRevisionsPerBatch ?? 200;
+  if (!Number.isSafeInteger(maxRevisions) || maxRevisions < 1 || maxRevisions > 1e4) {
+    throw new RangeError("maxRevisionsPerBatch must be between 1 and 10000");
+  }
+  const tables = {
+    projectId: options.projectId,
+    datasetId: options.datasetId,
+    rowsTableId: options.rowsTableId,
+    revisionsTableId: options.revisionsTableId
+  };
+  const dataset = options.bigquery.dataset(options.datasetId, {
+    ...options.projectId ? { projectId: options.projectId } : {},
+    ...options.location ? { location: options.location } : {}
+  });
+  async function loadOnce(tableId, jobId, lines, signal) {
+    signal?.throwIfAborted();
+    const directory = await fs.mkdtemp(path.join(tmpdir(), "adcp-warehouse-"));
+    const file = path.join(directory, `${jobId}.ndjson`);
+    try {
+      await fs.writeFile(file, lines.length ? lines.join("\n") + "\n" : "");
+      try {
+        await withinDeadline(
+          () => dataset.table(tableId).load(file, {
+            jobId,
+            sourceFormat: "NEWLINE_DELIMITED_JSON",
+            writeDisposition: "WRITE_APPEND",
+            jobTimeoutMs: String(loadTimeout),
+            ...options.location ? { location: options.location } : {},
+            ...options.labels ? { labels: { ...options.labels } } : {}
+          }),
+          loadTimeout,
+          signal
+        );
+      } catch (error) {
+        if (!isAlreadyExists(error)) throw error;
+        const metadata = await withinDeadline(
+          () => options.bigquery.job(jobId, options.location ? { location: options.location } : void 0).getMetadata(),
+          loadTimeout,
+          signal
+        );
+        assertJobSucceeded(metadata);
+      }
+    } finally {
+      await fs.rm(directory, { recursive: true, force: true });
+    }
+  }
+  return {
+    defaultTablesSql: reportingWarehouseDefaultTablesSqlV1(tables),
+    currentRowsViewSql: reportingWarehouseCurrentRowsViewSqlV1(tables),
+    async runOnce(runOptions = {}) {
+      const signal = runOptions.signal;
+      await options.db.query(
+        `INSERT INTO adcp_reporting_warehouse_sinks (sink_name) VALUES ($1) ON CONFLICT DO NOTHING`,
+        [options.name]
+      );
+      const state = (await options.db.query(
+        `SELECT committed_cursor, planned_from_cursor, planned_to_cursor, planned_revisions,
+                  planned_rows_attempt, planned_revisions_attempt
+             FROM adcp_reporting_warehouse_sinks WHERE sink_name = $1`,
+        [options.name]
+      )).rows[0];
+      let plan = state.planned_to_cursor && state.planned_revisions ? {
+        from: state.planned_from_cursor,
+        to: state.planned_to_cursor,
+        revisions: state.planned_revisions,
+        rowsAttempt: state.planned_rows_attempt,
+        revisionsAttempt: state.planned_revisions_attempt
+      } : void 0;
+      if (!plan) {
+        const page = await options.store.changesAfter({
+          ...state.committed_cursor ? { cursor: state.committed_cursor } : {},
+          ...options.account_id ? { account_id: options.account_id } : {},
+          kinds: ["revision"],
+          limit: maxRevisions
+        });
+        if (page.records.length === 0) {
+          if (page.cursor !== state.committed_cursor) await commit(page.cursor);
+          return { idle: true, revisions: 0, rows: 0, missing: [] };
+        }
+        plan = {
+          from: state.committed_cursor,
+          to: page.cursor,
+          revisions: page.records.map((record) => ({ id: record.record_id, account_id: record.account_id })),
+          rowsAttempt: 0,
+          revisionsAttempt: 0
+        };
+        await options.db.query(
+          `UPDATE adcp_reporting_warehouse_sinks
+              SET planned_from_cursor = $2, planned_to_cursor = $3, planned_revisions = $4::jsonb,
+                  planned_rows_attempt = 0, planned_revisions_attempt = 0, updated_at = clock_timestamp()
+            WHERE sink_name = $1`,
+          [options.name, plan.from, plan.to, JSON.stringify(plan.revisions)]
+        );
+      }
+      const rowLines = [];
+      const revisionLines = [];
+      const missing = [];
+      for (const planned of plan.revisions) {
+        signal?.throwIfAborted();
+        const revision = await options.store.getRevisionMetadata(planned.id, planned.account_id);
+        if (!revision) {
+          missing.push(planned.id);
+          continue;
+        }
+        const periodDate = sourceLocalDate(
+          revision.wireRevision.period?.start,
+          revision.wireRevision.period?.source_timezone
+        );
+        const base = {
+          reporting_revision_id: revision.reporting_revision_id,
+          reporting_obligation_id: revision.reporting_obligation_id,
+          account_id: planned.account_id,
+          revision_number: revision.revisionNumber,
+          finality: revision.finality,
+          period_date: periodDate
+        };
+        for (let offset = 0; offset < revision.binding.rowCount; ) {
+          const page = await options.store.readRevisionRows({
+            reporting_revision_id: revision.reporting_revision_id,
+            account_id: planned.account_id,
+            offset,
+            limit: 5e3,
+            ...signal ? { signal } : {}
+          });
+          if (!page || page.rows.length === 0) throw new Error("Reporting revision rows ended early");
+          page.rows.forEach((row, index) => {
+            const ordinal = offset + index;
+            const mapped = options.mapRow ? options.mapRow(row, { revision, ordinal }) : { row };
+            rowLines.push(JSON.stringify({ ...mapped, ...base, ordinal }));
+          });
+          offset += page.rows.length;
+        }
+        revisionLines.push(
+          JSON.stringify({
+            ...base,
+            supersedes_reporting_revision_id: revision.supersedes_reporting_revision_id ?? null,
+            period_start: revision.wireRevision.period?.start ?? null,
+            period_end: revision.wireRevision.period?.end ?? null,
+            source_timezone: revision.wireRevision.period?.source_timezone ?? null,
+            observed_at: revision.observedAt,
+            data_through: revision.dataThrough,
+            revision_content_sha256: revision.binding.sha256,
+            row_count: revision.binding.rowCount,
+            control_totals: revision.wireRevision.control_totals ?? []
+          })
+        );
+      }
+      const baseJobId = reportingWarehouseJobIdV1(options.name, plan.from, plan.to);
+      const suffix = (attempt) => attempt ? `_a${attempt}` : "";
+      const steps = [
+        { table: options.rowsTableId, kind: "rows", lines: rowLines, attempt: plan.rowsAttempt },
+        { table: options.revisionsTableId, kind: "revs", lines: revisionLines, attempt: plan.revisionsAttempt }
+      ];
+      for (const step of steps) {
+        if (!step.lines.length) continue;
+        try {
+          await loadOnce(step.table, `${baseJobId}_${step.kind}${suffix(step.attempt)}`, [...step.lines], signal);
+        } catch (error) {
+          if (isFinishedWithError(error)) {
+            const column = step.kind === "rows" ? "planned_rows_attempt" : "planned_revisions_attempt";
+            await options.db.query(
+              `UPDATE adcp_reporting_warehouse_sinks SET ${column} = ${column} + 1,
+                      updated_at = clock_timestamp() WHERE sink_name = $1`,
+              [options.name]
+            );
+          }
+          throw error;
+        }
+      }
+      await commit(plan.to);
+      return { idle: false, revisions: revisionLines.length, rows: rowLines.length, missing };
+    }
+  };
+  async function commit(cursor) {
+    await options.db.query(
+      `UPDATE adcp_reporting_warehouse_sinks
+          SET committed_cursor = $2, planned_from_cursor = NULL, planned_to_cursor = NULL,
+              planned_revisions = NULL, planned_rows_attempt = 0, planned_revisions_attempt = 0,
+              updated_at = clock_timestamp()
+        WHERE sink_name = $1`,
+      [options.name, cursor]
+    );
+    await options.store.saveFeedConsumerCursor(options.name, cursor);
+  }
+}
+function reportingWarehouseJobIdV1(name, from, to) {
+  return `adcp_rr_${createHash("sha256").update(JSON.stringify([name, from, to])).digest("hex").slice(0, 40)}`;
+}
+function qualified(tables, table) {
+  return `\`${tables.projectId ? `${tables.projectId}.` : ""}${tables.datasetId}.${table}\``;
+}
+function reportingWarehouseDefaultTablesSqlV1(tables) {
+  return `
+CREATE TABLE IF NOT EXISTS ${qualified(tables, tables.rowsTableId)} (
+  reporting_revision_id STRING NOT NULL,
+  reporting_obligation_id STRING NOT NULL,
+  account_id STRING NOT NULL,
+  revision_number INT64 NOT NULL,
+  finality STRING NOT NULL,
+  period_date DATE,
+  ordinal INT64 NOT NULL,
+  row JSON
+)
+PARTITION BY period_date
+CLUSTER BY account_id, reporting_revision_id;
+
+CREATE TABLE IF NOT EXISTS ${qualified(tables, tables.revisionsTableId)} (
+  reporting_revision_id STRING NOT NULL,
+  reporting_obligation_id STRING NOT NULL,
+  account_id STRING NOT NULL,
+  revision_number INT64 NOT NULL,
+  finality STRING NOT NULL,
+  period_date DATE,
+  supersedes_reporting_revision_id STRING,
+  period_start TIMESTAMP,
+  period_end TIMESTAMP,
+  source_timezone STRING,
+  observed_at TIMESTAMP,
+  data_through TIMESTAMP,
+  revision_content_sha256 STRING NOT NULL,
+  row_count INT64 NOT NULL,
+  control_totals JSON
+)
+PARTITION BY period_date
+CLUSTER BY account_id, reporting_obligation_id;`.trim();
+}
+function reportingWarehouseCurrentRowsViewSqlV1(tables) {
+  const view = tables.viewId ?? "current_rows";
+  if (!DATASET_OR_TABLE.test(view)) throw new TypeError("BigQuery viewId is invalid");
+  return `
+CREATE OR REPLACE VIEW ${qualified(tables, view)} AS
+SELECT row_data.*
+  FROM ${qualified(tables, tables.rowsTableId)} AS row_data
+  JOIN (
+    SELECT reporting_obligation_id,
+           ARRAY_AGG(reporting_revision_id ORDER BY revision_number DESC LIMIT 1)[OFFSET(0)] AS reporting_revision_id
+      FROM ${qualified(tables, tables.revisionsTableId)}
+     GROUP BY reporting_obligation_id
+  ) AS current_revision
+ USING (reporting_obligation_id, reporting_revision_id);`.trim();
+}
+function sourceLocalDate(start, timeZone) {
+  if (!start) return null;
+  const instant = new Date(start);
+  if (Number.isNaN(instant.getTime())) return null;
+  try {
+    const parts = new Intl.DateTimeFormat("en-CA", {
+      timeZone: timeZone ?? "UTC",
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit"
+    }).format(instant);
+    return parts;
+  } catch {
+    return instant.toISOString().slice(0, 10);
+  }
+}
+async function withinDeadline(operation, milliseconds, signal) {
+  signal?.throwIfAborted();
+  let timer;
+  let onAbort;
+  try {
+    return await Promise.race([
+      operation(),
+      new Promise((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error("BigQuery call exceeded its deadline; the batch will be retried")),
+          milliseconds
+        );
+        if (signal) {
+          onAbort = () => reject(signal.reason ?? new Error("aborted"));
+          signal.addEventListener("abort", onAbort, { once: true });
+        }
+      })
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+    if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+  }
+}
+function isAlreadyExists(error) {
+  const record = error;
+  return record?.code === 409 || !!record?.errors?.some((entry) => entry.reason === "duplicate");
+}
+function isFinishedWithError(error) {
+  return error?.adcpJobFailed === true;
+}
+function assertJobSucceeded(metadata) {
+  const record = Array.isArray(metadata) ? metadata[0] : metadata;
+  if (record?.status?.state !== "DONE") {
+    throw new Error("A BigQuery load job for this batch is still running; retry later");
+  }
+  if (record.status.errorResult) {
+    const failure = new Error("A BigQuery load job for this batch failed; it will be retried as a new attempt");
+    Object.defineProperty(failure, "adcpJobFailed", { value: true });
+    throw failure;
+  }
+}
+export {
+  REPORTING_WAREHOUSE_SINK_MIGRATION,
+  createBigQueryReportingWarehouseSinkV1,
+  reportingWarehouseCurrentRowsViewSqlV1,
+  reportingWarehouseDefaultTablesSqlV1,
+  reportingWarehouseJobIdV1
+};

package/dist/lib/reporting/ledger/handler.js

@@ -410,6 +410,12 @@ function createReportingStatusHandler(store, options) {
   };
 }
 const REPORTING_STATUS_REVISION_VIEW_MAX_ROWS = 1e4;
+function reportingRevisionNotFound() {
+  return new import_async_outcome.AdcpError("REFERENCE_NOT_FOUND", {
+    message: "Reporting revision is unavailable",
+    field: "reporting_revision_id"
+  });
+}
 function createReportingDeliveryHandler(store) {
   const activeReadsByAccount = /* @__PURE__ */ new Map();
   return async (request, context) => {
@@ -428,14 +434,15 @@ function createReportingDeliveryHandler(store) {
     try {
       const raw = request;
       if (typeof raw.reporting_revision_id !== "string" || !raw.reporting_revision_id) {
-        throw new Error("Ledger delivery reads require reporting_revision_id");
+        throw new import_async_outcome.AdcpError("VALIDATION_ERROR", {
+          message: "Ledger delivery reads require reporting_revision_id",
+          field: "reporting_revision_id"
+        });
       }
       const revision = await (0, import_revision_metadata.getRevisionMetadataFromStore)(store, raw.reporting_revision_id, accountId);
-      if (!revision) throw new Error("Reporting revision is unavailable");
+      if (!revision) throw reportingRevisionNotFound();
       const obligation = await store.getObligation(revision.reporting_obligation_id);
-      if (!obligation || obligation.account.account_id !== accountId) {
-        throw new Error("Reporting revision is unavailable");
-      }
+      if (!obligation || obligation.account.account_id !== accountId) throw reportingRevisionNotFound();
       const pagination = isRecord(raw.pagination) ? raw.pagination : {};
       const maxResults = typeof pagination.max_results === "number" && Number.isFinite(pagination.max_results) ? Math.max(1, Math.min(500, Math.trunc(pagination.max_results))) : 100;
       const totalCount = revision.binding.rowCount;
@@ -448,7 +455,7 @@ function createReportingDeliveryHandler(store) {
           }
           offset = cursor.offset;
         } catch {
-          throw new Error("Reporting delivery cursor is invalid");
+          throw reportingRevisionNotFound();
         }
       }
       let reportingRows = [];
@@ -464,14 +471,19 @@ function createReportingDeliveryHandler(store) {
           });
         } catch (error) {
           if ((0, import_row_storage.isReportingRowStoreError)(error)) {
-            if (error.code === "ROWS_EXPIRED") throw new Error("Reporting revision is unavailable");
+            if (error.code === "ROWS_EXPIRED") throw reportingRevisionNotFound();
             throw new import_async_outcome.AdcpError("SERVICE_UNAVAILABLE", {
               message: "Reporting revision rows are temporarily unavailable"
             });
           }
           throw error;
         }
-        if (!page || page.total !== totalCount) throw new Error("Reporting revision is unavailable");
+        if (!page) throw reportingRevisionNotFound();
+        if (page.total !== totalCount) {
+          throw new import_async_outcome.AdcpError("SERVICE_UNAVAILABLE", {
+            message: "Reporting revision rows are temporarily unavailable"
+          });
+        }
         reportingRows = page.rows;
       }
       const nextOffset = offset + reportingRows.length;

package/dist/lib/reporting/ledger/handler.mjs

@@ -393,6 +393,12 @@ function createReportingStatusHandler(store, options) {
   };
 }
 const REPORTING_STATUS_REVISION_VIEW_MAX_ROWS = 1e4;
+function reportingRevisionNotFound() {
+  return new AdcpError("REFERENCE_NOT_FOUND", {
+    message: "Reporting revision is unavailable",
+    field: "reporting_revision_id"
+  });
+}
 function createReportingDeliveryHandler(store) {
   const activeReadsByAccount = /* @__PURE__ */ new Map();
   return async (request, context) => {
@@ -411,14 +417,15 @@ function createReportingDeliveryHandler(store) {
     try {
       const raw = request;
       if (typeof raw.reporting_revision_id !== "string" || !raw.reporting_revision_id) {
-        throw new Error("Ledger delivery reads require reporting_revision_id");
+        throw new AdcpError("VALIDATION_ERROR", {
+          message: "Ledger delivery reads require reporting_revision_id",
+          field: "reporting_revision_id"
+        });
       }
       const revision = await getRevisionMetadataFromStore(store, raw.reporting_revision_id, accountId);
-      if (!revision) throw new Error("Reporting revision is unavailable");
+      if (!revision) throw reportingRevisionNotFound();
       const obligation = await store.getObligation(revision.reporting_obligation_id);
-      if (!obligation || obligation.account.account_id !== accountId) {
-        throw new Error("Reporting revision is unavailable");
-      }
+      if (!obligation || obligation.account.account_id !== accountId) throw reportingRevisionNotFound();
       const pagination = isRecord(raw.pagination) ? raw.pagination : {};
       const maxResults = typeof pagination.max_results === "number" && Number.isFinite(pagination.max_results) ? Math.max(1, Math.min(500, Math.trunc(pagination.max_results))) : 100;
       const totalCount = revision.binding.rowCount;
@@ -431,7 +438,7 @@ function createReportingDeliveryHandler(store) {
           }
           offset = cursor.offset;
         } catch {
-          throw new Error("Reporting delivery cursor is invalid");
+          throw reportingRevisionNotFound();
         }
       }
       let reportingRows = [];
@@ -447,14 +454,19 @@ function createReportingDeliveryHandler(store) {
           });
         } catch (error) {
           if (isReportingRowStoreError(error)) {
-            if (error.code === "ROWS_EXPIRED") throw new Error("Reporting revision is unavailable");
+            if (error.code === "ROWS_EXPIRED") throw reportingRevisionNotFound();
             throw new AdcpError("SERVICE_UNAVAILABLE", {
               message: "Reporting revision rows are temporarily unavailable"
             });
           }
           throw error;
         }
-        if (!page || page.total !== totalCount) throw new Error("Reporting revision is unavailable");
+        if (!page) throw reportingRevisionNotFound();
+        if (page.total !== totalCount) {
+          throw new AdcpError("SERVICE_UNAVAILABLE", {
+            message: "Reporting revision rows are temporarily unavailable"
+          });
+        }
         reportingRows = page.rows;
       }
       const nextOffset = offset + reportingRows.length;

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

@@ -137,6 +137,17 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
     private readonly rowStorageWrites;
     private readonly changeFeed;
     constructor(pool: ReportingPgPool, options?: PostgresReportingLedgerStoreOptions);
+    /** Whether this store writes the host change feed (`changeFeed: true`). */
+    get changeFeedEnabled(): boolean;
+    /**
+     * Delete expired cursor snapshots and changes checkpoints, a bounded batch
+     * at a time. The store-bound form of `sweepExpiredReportingLedgerState`, for
+     * hosts that hold the store but not the pool.
+     */
+    sweepExpiredState(limit?: number): Promise<{
+        snapshotsDeleted: number;
+        checkpointsDeleted: number;
+    }>;
     /** Append one host change-feed row inside the caller's account-locked transaction. */
     private appendChange;
     /** Probe and register row storage when enabled. Safe to call repeatedly. */
@@ -280,10 +291,20 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
      *
      * Planners skip retired periods, and `ledger_retained_from` advances past
      * them because their obligations no longer exist.
+     *
+     * When the change-feed tables exist, a period that is not yet retiring is
+     * also held while any live registered feed consumer (updated within
+     * `maxFeedHoldDays`, default 7) has not passed that period's change rows in
+     * the consumer's own feed order, the same rule `pruneChanges` applies. A
+     * held period is simply not a candidate this pass. A consumer that stays
+     * silent past `maxFeedHoldDays` stops holding, so retention is never
+     * blocked forever; it then falls behind retention and a sink sees the
+     * retired revisions as missing.
      */
     retireExpiredPeriods(input: {
         statusRetentionDays: number;
         recordRetentionDays?: number;
+        maxFeedHoldDays?: number;
         limit?: number;
         account_id?: string;
         signal?: AbortSignal;

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

@@ -137,6 +137,17 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
     private readonly rowStorageWrites;
     private readonly changeFeed;
     constructor(pool: ReportingPgPool, options?: PostgresReportingLedgerStoreOptions);
+    /** Whether this store writes the host change feed (`changeFeed: true`). */
+    get changeFeedEnabled(): boolean;
+    /**
+     * Delete expired cursor snapshots and changes checkpoints, a bounded batch
+     * at a time. The store-bound form of `sweepExpiredReportingLedgerState`, for
+     * hosts that hold the store but not the pool.
+     */
+    sweepExpiredState(limit?: number): Promise<{
+        snapshotsDeleted: number;
+        checkpointsDeleted: number;
+    }>;
     /** Append one host change-feed row inside the caller's account-locked transaction. */
     private appendChange;
     /** Probe and register row storage when enabled. Safe to call repeatedly. */
@@ -280,10 +291,20 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
      *
      * Planners skip retired periods, and `ledger_retained_from` advances past
      * them because their obligations no longer exist.
+     *
+     * When the change-feed tables exist, a period that is not yet retiring is
+     * also held while any live registered feed consumer (updated within
+     * `maxFeedHoldDays`, default 7) has not passed that period's change rows in
+     * the consumer's own feed order, the same rule `pruneChanges` applies. A
+     * held period is simply not a candidate this pass. A consumer that stays
+     * silent past `maxFeedHoldDays` stops holding, so retention is never
+     * blocked forever; it then falls behind retention and a sink sees the
+     * retired revisions as missing.
      */
     retireExpiredPeriods(input: {
         statusRetentionDays: number;
         recordRetentionDays?: number;
+        maxFeedHoldDays?: number;
         limit?: number;
         account_id?: string;
         signal?: AbortSignal;

package/dist/lib/reporting/ledger/postgres.js

@@ -424,6 +424,18 @@ class PostgresReportingLedgerStore {
   rowStorage;
   rowStorageWrites;
   changeFeed;
+  /** Whether this store writes the host change feed (`changeFeed: true`). */
+  get changeFeedEnabled() {
+    return this.changeFeed;
+  }
+  /**
+   * Delete expired cursor snapshots and changes checkpoints, a bounded batch
+   * at a time. The store-bound form of `sweepExpiredReportingLedgerState`, for
+   * hosts that hold the store but not the pool.
+   */
+  async sweepExpiredState(limit = 1e3) {
+    return sweepExpiredReportingLedgerState(this.pool, limit);
+  }
   /** Append one host change-feed row inside the caller's account-locked transaction. */
   async appendChange(client, kind, accountId, recordId, obligationId) {
     if (!this.changeFeed) return;
@@ -1289,6 +1301,15 @@ ${managedDueArm}       )
    *
    * Planners skip retired periods, and `ledger_retained_from` advances past
    * them because their obligations no longer exist.
+   *
+   * When the change-feed tables exist, a period that is not yet retiring is
+   * also held while any live registered feed consumer (updated within
+   * `maxFeedHoldDays`, default 7) has not passed that period's change rows in
+   * the consumer's own feed order, the same rule `pruneChanges` applies. A
+   * held period is simply not a candidate this pass. A consumer that stays
+   * silent past `maxFeedHoldDays` stops holding, so retention is never
+   * blocked forever; it then falls behind retention and a sink sees the
+   * retired revisions as missing.
    */
   async retireExpiredPeriods(input) {
     if (!Number.isSafeInteger(input.statusRetentionDays) || input.statusRetentionDays < 1) {
@@ -1300,8 +1321,18 @@ ${managedDueArm}       )
     }
     const limit = input.limit ?? 100;
     positiveInteger(limit, "limit");
+    const holdDays = input.maxFeedHoldDays ?? 7;
+    positiveInteger(holdDays, "maxFeedHoldDays");
     const tables = await this.optionalTables();
     const materializationHold = tables.has("adcp_reporting_materializations") ? `AND NOT EXISTS (SELECT 1 FROM adcp_reporting_materializations hold WHERE hold.obligation_id = obligation.obligation_id)` : "";
+    const feedHold = tables.has("adcp_reporting_changes") && tables.has("adcp_reporting_feed_consumers") ? `AND NOT EXISTS (
+                  SELECT 1 FROM adcp_reporting_changes change
+                    JOIN adcp_reporting_feed_consumers consumer
+                      ON consumer.updated_at > clock_timestamp() - ($4::integer * INTERVAL '1 day')
+                   WHERE change.obligation_id = obligation.obligation_id
+                     AND ((consumer.account_id IS NULL
+                           AND (change.xid, change.seq) > (consumer.cursor_xid, consumer.cursor_seq))
+                       OR (consumer.account_id = change.account_id AND change.seq > consumer.cursor_seq)))` : "";
     const candidates = await this.query(
       `SELECT obligation_id, account_id FROM (
          SELECT tombstone.obligation_id, tombstone.account_id, 0 AS resume, tombstone.period_end
@@ -1322,10 +1353,11 @@ ${managedDueArm}       )
             AND NOT EXISTS (SELECT 1 FROM adcp_reporting_obligation_tombstones tombstone
                              WHERE tombstone.obligation_id = obligation.obligation_id)
             ${materializationHold}
+            ${feedHold}
        ) candidate
        ORDER BY resume, period_end, obligation_id
        LIMIT $1`,
-      [limit, input.account_id ?? null, recordDays]
+      feedHold ? [limit, input.account_id ?? null, recordDays, holdDays] : [limit, input.account_id ?? null, recordDays]
     );
     let retired = 0;
     const failed = [];
@@ -1497,7 +1529,8 @@ ${managedDueArm}       )
       `SELECT table_name AS name FROM information_schema.tables
         WHERE table_schema = current_schema()
           AND table_name IN ('adcp_reporting_row_sets', 'adcp_reporting_row_write_intents',
-                             'adcp_reporting_materializations')`
+                             'adcp_reporting_materializations', 'adcp_reporting_changes',
+                             'adcp_reporting_feed_consumers')`
     );
     return new Set(result.rows.map((row) => row.name));
   }