@adcp/sdk 15.8.1 → 15.9.1

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

@@ -253,9 +253,21 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
      * Host change feed. Omit `cursor` to start from the oldest retained change.
      * Account-scoped feeds order by sequence; the deployment-wide feed orders by
      * `(xid, seq)` and returns only changes whose transaction precedes every
-     * transaction still in flight, so no commit is ever skipped. A cursor older
+     * transaction still in flight, so no commit is ever skipped. An account page
+     * also ends before the first change whose transaction has not finished, as
+     * defense in depth against a change that commits late. An empty page can
+     * therefore mean either caught up or held back by an older open transaction.
+     * A ledger database must have exactly one writer SDK; see
+     * `docs/guides/REPORTING-LEDGER.md`. A cursor older
      * than the retained history throws `ReportingChangeCursorExpiredError`;
      * resynchronize from `listCurrentRevisions`.
+     *
+     * A read without a `cursor` can throw `ReportingChangeCursorExpiredError`
+     * (`code === 'CURSOR_EXPIRED'`) too. The horizon is re-read after the page,
+     * so a prune that commits mid-read rejects the page instead of returning one
+     * that silently skips the pruned changes. Retrying the read starts from the
+     * new, later horizon. Match on `error.code` rather than `instanceof`, which
+     * fails when the error crosses a CJS/ESM module boundary.
      */
     changesAfter(input?: {
         cursor?: string;
@@ -266,8 +278,35 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
     /**
      * Record a named durable consumer's position. Registered consumers hold
      * back change-table pruning until `maxFeedHoldDays` after their last update.
+     *
+     * Checkpoints are forward-only within a feed scope: a cursor behind the
+     * saved one is ignored, so a delayed or stale acknowledgment cannot pull the
+     * retention hold back. Resolves `true` when the checkpoint was written and
+     * `false` when it was ignored (behind the saved position, or equal with
+     * `refreshUnchanged: false`). To rewind a consumer deliberately, for example
+     * to replay changes, pass `rewind: true`; the saved position and retention
+     * hold then move to `cursor` and the write always applies, even with
+     * `refreshUnchanged: false`. The cursor is not checked against the
+     * retention horizon: it must still be inside the retained history or the
+     * next read throws `ReportingChangeCursorExpiredError`. Any change of
+     * `account_id` (account to deployment, deployment to account, or between
+     * accounts) always replaces the position. The feed scope is read from the
+     * cursor itself, so only pass cursors your own code obtained from
+     * `changesAfter`, never ones supplied by an untrusted caller.
+     *
+     * Set `refreshUnchanged: false` to recover an acknowledgment without
+     * renewing the retention hold when its position has not advanced.
+     */
+    saveFeedConsumerCursor(name: string, cursor: string, options?: {
+        refreshUnchanged?: boolean;
+        rewind?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Unregister a durable consumer so it stops holding back change-table
+     * pruning and period retention. Resolves `true` when a registration was
+     * removed. Saving a cursor under the same name registers it again.
      */
-    saveFeedConsumerCursor(name: string, cursor: string): Promise<void>;
+    removeFeedConsumer(name: string): Promise<boolean>;
     /**
      * Delete change rows older than `changeRetentionDays` that every consumer
      * updated within `maxFeedHoldDays` has passed, and advance the expiry
@@ -317,12 +356,30 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
     }): Promise<{
         retired: number;
         failed: string[];
-        /** Secret-free cause per failed period: a row-store code or the error class name. */
+        /** Secret-free cause per period that failed this pass: a row-store code or the error class name. */
         failures: {
             reporting_obligation_id: string;
             cause: string;
         }[];
+        /** Retiring periods currently backing off after a failure; they are not attempted this pass. */
+        deferred: number;
+        /**
+         * Periods that have failed at least five attempts and
+         * are still retiring (at most 20, worst first). They need operator attention, for example a
+         * removed binding or a permanent provider error.
+         */
+        stuck: {
+            reporting_obligation_id: string;
+            attempts: number;
+            cause: string;
+        }[];
     }>;
+    /**
+     * Record a failed retirement attempt on the period's tombstone and push its next
+     * attempt out by an exponential backoff. Best effort: a failure to record only
+     * means the period is retried on the next pass.
+     */
+    private recordRetirementFailure;
     private retirePeriod;
     /**
      * Compact superseded snapshot revisions to metadata only, as adcontextprotocol/adcp#8100
@@ -394,11 +451,26 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
     sweepRowWriteIntents(input?: {
         limit?: number;
         account_id?: string;
+        overdueAfterSeconds?: number;
         signal?: AbortSignal;
     }): Promise<{
         swept: number;
         objectsDeleted: number;
+        /** Intents whose sweep failed this pass. Each backs off before its next attempt. */
         failed: number;
+        /**
+         * Expired intents with objects to delete through a binding this host does not configure. They
+         * are left untouched for a host that configures it; they are not failures of this host.
+         */
+        skippedUnconfigured: number;
+        /** Expired intents backing off after a failed sweep, not attempted this pass. */
+        deferred: number;
+        /**
+         * Intents expired for longer than `overdueAfterSeconds` (default 24 hours) and still not swept,
+         * including ones backing off. Their objects are leaking: check that a host configures their
+         * binding and that provider deletes succeed.
+         */
+        overdue: number;
     }>;
     /**
      * Delete external row objects, skipping any object another row set still references.

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

@@ -253,9 +253,21 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
      * Host change feed. Omit `cursor` to start from the oldest retained change.
      * Account-scoped feeds order by sequence; the deployment-wide feed orders by
      * `(xid, seq)` and returns only changes whose transaction precedes every
-     * transaction still in flight, so no commit is ever skipped. A cursor older
+     * transaction still in flight, so no commit is ever skipped. An account page
+     * also ends before the first change whose transaction has not finished, as
+     * defense in depth against a change that commits late. An empty page can
+     * therefore mean either caught up or held back by an older open transaction.
+     * A ledger database must have exactly one writer SDK; see
+     * `docs/guides/REPORTING-LEDGER.md`. A cursor older
      * than the retained history throws `ReportingChangeCursorExpiredError`;
      * resynchronize from `listCurrentRevisions`.
+     *
+     * A read without a `cursor` can throw `ReportingChangeCursorExpiredError`
+     * (`code === 'CURSOR_EXPIRED'`) too. The horizon is re-read after the page,
+     * so a prune that commits mid-read rejects the page instead of returning one
+     * that silently skips the pruned changes. Retrying the read starts from the
+     * new, later horizon. Match on `error.code` rather than `instanceof`, which
+     * fails when the error crosses a CJS/ESM module boundary.
      */
     changesAfter(input?: {
         cursor?: string;
@@ -266,8 +278,35 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
     /**
      * Record a named durable consumer's position. Registered consumers hold
      * back change-table pruning until `maxFeedHoldDays` after their last update.
+     *
+     * Checkpoints are forward-only within a feed scope: a cursor behind the
+     * saved one is ignored, so a delayed or stale acknowledgment cannot pull the
+     * retention hold back. Resolves `true` when the checkpoint was written and
+     * `false` when it was ignored (behind the saved position, or equal with
+     * `refreshUnchanged: false`). To rewind a consumer deliberately, for example
+     * to replay changes, pass `rewind: true`; the saved position and retention
+     * hold then move to `cursor` and the write always applies, even with
+     * `refreshUnchanged: false`. The cursor is not checked against the
+     * retention horizon: it must still be inside the retained history or the
+     * next read throws `ReportingChangeCursorExpiredError`. Any change of
+     * `account_id` (account to deployment, deployment to account, or between
+     * accounts) always replaces the position. The feed scope is read from the
+     * cursor itself, so only pass cursors your own code obtained from
+     * `changesAfter`, never ones supplied by an untrusted caller.
+     *
+     * Set `refreshUnchanged: false` to recover an acknowledgment without
+     * renewing the retention hold when its position has not advanced.
+     */
+    saveFeedConsumerCursor(name: string, cursor: string, options?: {
+        refreshUnchanged?: boolean;
+        rewind?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Unregister a durable consumer so it stops holding back change-table
+     * pruning and period retention. Resolves `true` when a registration was
+     * removed. Saving a cursor under the same name registers it again.
      */
-    saveFeedConsumerCursor(name: string, cursor: string): Promise<void>;
+    removeFeedConsumer(name: string): Promise<boolean>;
     /**
      * Delete change rows older than `changeRetentionDays` that every consumer
      * updated within `maxFeedHoldDays` has passed, and advance the expiry
@@ -317,12 +356,30 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
     }): Promise<{
         retired: number;
         failed: string[];
-        /** Secret-free cause per failed period: a row-store code or the error class name. */
+        /** Secret-free cause per period that failed this pass: a row-store code or the error class name. */
         failures: {
             reporting_obligation_id: string;
             cause: string;
         }[];
+        /** Retiring periods currently backing off after a failure; they are not attempted this pass. */
+        deferred: number;
+        /**
+         * Periods that have failed at least five attempts and
+         * are still retiring (at most 20, worst first). They need operator attention, for example a
+         * removed binding or a permanent provider error.
+         */
+        stuck: {
+            reporting_obligation_id: string;
+            attempts: number;
+            cause: string;
+        }[];
     }>;
+    /**
+     * Record a failed retirement attempt on the period's tombstone and push its next
+     * attempt out by an exponential backoff. Best effort: a failure to record only
+     * means the period is retried on the next pass.
+     */
+    private recordRetirementFailure;
     private retirePeriod;
     /**
      * Compact superseded snapshot revisions to metadata only, as adcontextprotocol/adcp#8100
@@ -394,11 +451,26 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
     sweepRowWriteIntents(input?: {
         limit?: number;
         account_id?: string;
+        overdueAfterSeconds?: number;
         signal?: AbortSignal;
     }): Promise<{
         swept: number;
         objectsDeleted: number;
+        /** Intents whose sweep failed this pass. Each backs off before its next attempt. */
         failed: number;
+        /**
+         * Expired intents with objects to delete through a binding this host does not configure. They
+         * are left untouched for a host that configures it; they are not failures of this host.
+         */
+        skippedUnconfigured: number;
+        /** Expired intents backing off after a failed sweep, not attempted this pass. */
+        deferred: number;
+        /**
+         * Intents expired for longer than `overdueAfterSeconds` (default 24 hours) and still not swept,
+         * including ones backing off. Their objects are leaking: check that a host configures their
+         * binding and that provider deletes succeed.
+         */
+        overdue: number;
     }>;
     /**
      * Delete external row objects, skipping any object another row set still references.

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

@@ -313,6 +313,25 @@ CREATE TABLE IF NOT EXISTS adcp_reporting_obligation_tombstones (
 );
 CREATE INDEX IF NOT EXISTS adcp_reporting_obligation_tombstones_account
   ON adcp_reporting_obligation_tombstones (account_id, configuration_id, period_ordinal);
+-- Retirement retry state. A period whose external deletes fail on every pass
+-- backs off instead of holding a slot at the head of every pass. Guarded on the
+-- catalog because ADD COLUMN IF NOT EXISTS takes ACCESS EXCLUSIVE even when the
+-- column exists, which would block a rerun behind ordinary traffic.
+DO $tombstone_retry$
+DECLARE
+  tombstones regclass := to_regclass('adcp_reporting_obligation_tombstones');
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_attribute WHERE attrelid = tombstones AND attname = 'attempts' AND NOT attisdropped) THEN
+    ALTER TABLE adcp_reporting_obligation_tombstones ADD COLUMN attempts INTEGER NOT NULL DEFAULT 0;
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_attribute WHERE attrelid = tombstones AND attname = 'next_attempt_at' AND NOT attisdropped) THEN
+    ALTER TABLE adcp_reporting_obligation_tombstones ADD COLUMN next_attempt_at TIMESTAMPTZ;
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_attribute WHERE attrelid = tombstones AND attname = 'last_failure' AND NOT attisdropped) THEN
+    ALTER TABLE adcp_reporting_obligation_tombstones ADD COLUMN last_failure TEXT;
+  END IF;
+END
+$tombstone_retry$;
 `.trim();
 const REPORTING_LEDGER_FINALITY_FENCE_CONSTRAINT = "adcp_reporting_transitions_finality_recorded";
 const REPORTING_LEDGER_FINALITY_WRITER_FENCE_MIGRATION = `
@@ -357,6 +376,10 @@ class ReportingLedgerContinuityError extends Error {
     this.name = "ReportingLedgerContinuityError";
   }
 }
+const REPORTING_PERSISTENT_FAILURE_ATTEMPTS = 5;
+function backoffIntervalSql(attemptsExpr) {
+  return `(LEAST(21600, 60 * power(2, LEAST(${attemptsExpr} - 1, 12))) * INTERVAL '1 second')`;
+}
 async function sweepExpiredReportingLedgerState(pool, limit = 1e3) {
   positiveInteger(limit, "limit");
   if (limit > 1e4) throw new RangeError("limit must not exceed 10000");
@@ -1156,9 +1179,21 @@ ${managedDueArm}       )
    * Host change feed. Omit `cursor` to start from the oldest retained change.
    * Account-scoped feeds order by sequence; the deployment-wide feed orders by
    * `(xid, seq)` and returns only changes whose transaction precedes every
-   * transaction still in flight, so no commit is ever skipped. A cursor older
+   * transaction still in flight, so no commit is ever skipped. An account page
+   * also ends before the first change whose transaction has not finished, as
+   * defense in depth against a change that commits late. An empty page can
+   * therefore mean either caught up or held back by an older open transaction.
+   * A ledger database must have exactly one writer SDK; see
+   * `docs/guides/REPORTING-LEDGER.md`. A cursor older
    * than the retained history throws `ReportingChangeCursorExpiredError`;
    * resynchronize from `listCurrentRevisions`.
+   *
+   * A read without a `cursor` can throw `ReportingChangeCursorExpiredError`
+   * (`code === 'CURSOR_EXPIRED'`) too. The horizon is re-read after the page,
+   * so a prune that commits mid-read rejects the page instead of returning one
+   * that silently skips the pruned changes. Retrying the read starts from the
+   * new, later horizon. Match on `error.code` rather than `instanceof`, which
+   * fails when the error crosses a CJS/ESM module boundary.
    */
   async changesAfter(input = {}) {
     if (!this.changeFeed) throw new Error("changesAfter requires the store changeFeed option");
@@ -1167,7 +1202,7 @@ ${managedDueArm}       )
     if (limit > 1e4) throw new RangeError("changesAfter limit must not exceed 10000");
     const account = input.account_id ?? null;
     const cursor = input.cursor === void 0 ? void 0 : (0, import_change_feed.decodeReportingChangeCursorV1)(input.cursor, account);
-    const horizon = account !== null ? {
+    const readHorizon = async () => account !== null ? {
       seq: (await this.query(
         `SELECT pruned_through_seq::text AS seq FROM adcp_reporting_change_account_horizon
                     WHERE account_id = $1`,
@@ -1177,10 +1212,21 @@ ${managedDueArm}       )
       `SELECT pruned_through_xid::text AS xid, pruned_through_seq::text AS seq
                  FROM adcp_reporting_change_horizon WHERE singleton`
     )).rows[0] ?? { xid: "0", seq: "0" };
-    if (cursor) {
-      const behind = account !== null ? BigInt(horizon.seq) > BigInt(cursor.seq) : BigInt(horizon.xid) > BigInt(cursor.xid) || BigInt(horizon.xid) === BigInt(cursor.xid) && BigInt(horizon.seq) > BigInt(cursor.seq);
-      if (behind) throw new import_change_feed.ReportingChangeCursorExpiredError();
-    }
+    const assertRetained = (position2, horizon2) => {
+      const behind = account !== null ? BigInt(horizon2.seq) > BigInt(position2.seq) : BigInt(horizon2.xid) > BigInt(position2.xid) || BigInt(horizon2.xid) === BigInt(position2.xid) && BigInt(horizon2.seq) > BigInt(position2.seq);
+      if (behind) {
+        throw new import_change_feed.ReportingChangeCursorExpiredError(
+          (0, import_change_feed.encodeReportingChangeCursorV1)({
+            v: 1,
+            account,
+            seq: position2.seq,
+            ...account === null ? { xid: position2.xid } : {}
+          })
+        );
+      }
+    };
+    const horizon = await readHorizon();
+    if (cursor) assertRetained(cursor, horizon);
     const position = cursor ?? {
       v: 1,
       account,
@@ -1191,7 +1237,8 @@ ${managedDueArm}       )
     const columns = `seq::text AS seq, xid::text AS xid, account_id, record_kind, record_id, obligation_id,
       to_char(recorded_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"') AS recorded_at`;
     const result = account !== null ? await this.query(
-      `SELECT ${columns} FROM adcp_reporting_changes
+      `SELECT ${columns}, xid >= pg_snapshot_xmin(pg_current_snapshot()) AS in_flight
+               FROM adcp_reporting_changes
               WHERE account_id = $1 AND seq > $2::bigint AND ($3::text[] IS NULL OR record_kind = ANY($3))
               ORDER BY adcp_reporting_changes.seq LIMIT $4`,
       [account, position.seq, kinds, limit]
@@ -1203,6 +1250,11 @@ ${managedDueArm}       )
               ORDER BY adcp_reporting_changes.xid, adcp_reporting_changes.seq LIMIT $4`,
       [position.xid ?? "0", position.seq, kinds, limit]
     );
+    if (account !== null) {
+      const blocked = result.rows.findIndex((row) => row.in_flight);
+      if (blocked !== -1) result.rows.length = blocked;
+    }
+    assertRetained(position, await readHorizon());
     const last = result.rows.at(-1);
     const next = last ? (0, import_change_feed.encodeReportingChangeCursorV1)({ v: 1, account, seq: last.seq, ...account === null ? { xid: last.xid } : {} }) : input.cursor ?? (0, import_change_feed.encodeReportingChangeCursorV1)(position);
     return {
@@ -1219,8 +1271,26 @@ ${managedDueArm}       )
   /**
    * Record a named durable consumer's position. Registered consumers hold
    * back change-table pruning until `maxFeedHoldDays` after their last update.
+   *
+   * Checkpoints are forward-only within a feed scope: a cursor behind the
+   * saved one is ignored, so a delayed or stale acknowledgment cannot pull the
+   * retention hold back. Resolves `true` when the checkpoint was written and
+   * `false` when it was ignored (behind the saved position, or equal with
+   * `refreshUnchanged: false`). To rewind a consumer deliberately, for example
+   * to replay changes, pass `rewind: true`; the saved position and retention
+   * hold then move to `cursor` and the write always applies, even with
+   * `refreshUnchanged: false`. The cursor is not checked against the
+   * retention horizon: it must still be inside the retained history or the
+   * next read throws `ReportingChangeCursorExpiredError`. Any change of
+   * `account_id` (account to deployment, deployment to account, or between
+   * accounts) always replaces the position. The feed scope is read from the
+   * cursor itself, so only pass cursors your own code obtained from
+   * `changesAfter`, never ones supplied by an untrusted caller.
+   *
+   * Set `refreshUnchanged: false` to recover an acknowledgment without
+   * renewing the retention hold when its position has not advanced.
    */
-  async saveFeedConsumerCursor(name, cursor) {
+  async saveFeedConsumerCursor(name, cursor, options = {}) {
     if (!this.changeFeed) throw new Error("saveFeedConsumerCursor requires the store changeFeed option");
     let account;
     try {
@@ -1230,14 +1300,45 @@ ${managedDueArm}       )
       throw new RangeError("feed consumer cursor is invalid");
     }
     const decoded = (0, import_change_feed.decodeReportingChangeCursorV1)(cursor, account);
-    await this.query(
+    const result = await this.query(
       `INSERT INTO adcp_reporting_feed_consumers (consumer_name, account_id, cursor_xid, cursor_seq)
        VALUES ($1, $2, $3::text::xid8, $4::bigint)
        ON CONFLICT (consumer_name) DO UPDATE
           SET account_id = EXCLUDED.account_id, cursor_xid = EXCLUDED.cursor_xid,
-              cursor_seq = EXCLUDED.cursor_seq, updated_at = clock_timestamp()`,
-      [name, account, account === null ? decoded.xid : null, decoded.seq]
+              cursor_seq = EXCLUDED.cursor_seq, updated_at = clock_timestamp()
+        WHERE $6::boolean
+           OR adcp_reporting_feed_consumers.account_id IS DISTINCT FROM EXCLUDED.account_id
+           OR CASE WHEN EXCLUDED.account_id IS NULL
+              THEN (adcp_reporting_feed_consumers.cursor_xid, adcp_reporting_feed_consumers.cursor_seq)
+                   < (EXCLUDED.cursor_xid, EXCLUDED.cursor_seq)
+                OR ($5::boolean AND (adcp_reporting_feed_consumers.cursor_xid, adcp_reporting_feed_consumers.cursor_seq)
+                   = (EXCLUDED.cursor_xid, EXCLUDED.cursor_seq))
+              ELSE adcp_reporting_feed_consumers.cursor_seq < EXCLUDED.cursor_seq
+                OR ($5::boolean AND adcp_reporting_feed_consumers.cursor_seq = EXCLUDED.cursor_seq) END
+       RETURNING consumer_name`,
+      [
+        name,
+        account,
+        account === null ? decoded.xid : null,
+        decoded.seq,
+        options.refreshUnchanged !== false,
+        options.rewind === true
+      ]
     );
+    return result.rows.length > 0;
+  }
+  /**
+   * Unregister a durable consumer so it stops holding back change-table
+   * pruning and period retention. Resolves `true` when a registration was
+   * removed. Saving a cursor under the same name registers it again.
+   */
+  async removeFeedConsumer(name) {
+    if (!this.changeFeed) throw new Error("removeFeedConsumer requires the store changeFeed option");
+    const result = await this.query(
+      `DELETE FROM adcp_reporting_feed_consumers WHERE consumer_name = $1 RETURNING consumer_name`,
+      [name]
+    );
+    return result.rows.length > 0;
   }
   /**
    * Delete change rows older than `changeRetentionDays` that every consumer
@@ -1350,11 +1451,14 @@ ${managedDueArm}       )
                        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
+         SELECT tombstone.obligation_id, tombstone.account_id, 0 AS resume, tombstone.attempts, tombstone.period_end,
+                CASE WHEN row_number() OVER (ORDER BY tombstone.attempts, tombstone.period_end, tombstone.obligation_id)
+                          <= (($1::integer + 1) / 2) THEN 0 ELSE 1 END AS tier
            FROM adcp_reporting_obligation_tombstones tombstone
           WHERE tombstone.state = 'retiring' AND ($2::text IS NULL OR tombstone.account_id = $2)
+            AND (tombstone.next_attempt_at IS NULL OR tombstone.next_attempt_at <= clock_timestamp())
          UNION ALL
-         SELECT obligation.obligation_id, obligation.account_id, 1, obligation.period_end
+         (SELECT obligation.obligation_id, obligation.account_id, 1, 0, obligation.period_end, 0
            FROM adcp_reporting_obligations obligation
           WHERE ($2::text IS NULL OR obligation.account_id = $2)
             AND obligation.period_end + ($3::integer * INTERVAL '1 day') <= clock_timestamp()
@@ -1369,8 +1473,10 @@ ${managedDueArm}       )
                              WHERE tombstone.obligation_id = obligation.obligation_id)
             ${materializationHold}
             ${feedHold}
+          ORDER BY obligation.period_end, obligation.obligation_id
+          LIMIT $1)
        ) candidate
-       ORDER BY resume, period_end, obligation_id
+       ORDER BY tier, resume, attempts, period_end, obligation_id
        LIMIT $1`,
       feedHold ? [limit, input.account_id ?? null, recordDays, holdDays] : [limit, input.account_id ?? null, recordDays]
     );
@@ -1384,14 +1490,49 @@ ${managedDueArm}       )
         retired += 1;
       } catch (error) {
         if (error instanceof ReportingLedgerPeriodRetiredError) continue;
+        const cause = (0, import_row_storage.isReportingRowStoreError)(error) ? error.code : error instanceof Error ? error.name : "Error";
         failed.push(candidate.obligation_id);
-        failures.push({
-          reporting_obligation_id: candidate.obligation_id,
-          cause: (0, import_row_storage.isReportingRowStoreError)(error) ? error.code : error instanceof Error ? error.name : "Error"
-        });
+        failures.push({ reporting_obligation_id: candidate.obligation_id, cause });
+        if (!input.signal?.aborted) await this.recordRetirementFailure(candidate.obligation_id, cause);
       }
     }
-    return { retired, failed, failures };
+    const scope = input.account_id ?? null;
+    const deferred = Number(
+      (await this.query(
+        `SELECT count(*) AS n FROM adcp_reporting_obligation_tombstones
+            WHERE state = 'retiring' AND next_attempt_at > clock_timestamp()
+              AND ($1::text IS NULL OR account_id = $1)`,
+        [scope]
+      )).rows[0].n
+    );
+    const stuck = (await this.query(
+      `SELECT obligation_id, attempts, last_failure FROM adcp_reporting_obligation_tombstones
+          WHERE state = 'retiring' AND attempts >= $2 AND ($1::text IS NULL OR account_id = $1)
+          ORDER BY attempts DESC, retiring_at, obligation_id LIMIT 20`,
+      [scope, REPORTING_PERSISTENT_FAILURE_ATTEMPTS]
+    )).rows.map((row) => ({
+      reporting_obligation_id: row.obligation_id,
+      attempts: row.attempts,
+      cause: row.last_failure ?? "Error"
+    }));
+    return { retired, failed, failures, deferred, stuck };
+  }
+  /**
+   * Record a failed retirement attempt on the period's tombstone and push its next
+   * attempt out by an exponential backoff. Best effort: a failure to record only
+   * means the period is retried on the next pass.
+   */
+  async recordRetirementFailure(obligationId, cause) {
+    try {
+      await this.query(
+        `UPDATE adcp_reporting_obligation_tombstones
+            SET attempts = attempts + 1, last_failure = $2,
+                next_attempt_at = clock_timestamp() + ${backoffIntervalSql("attempts + 1")}
+          WHERE obligation_id = $1 AND state = 'retiring'`,
+        [obligationId, cause]
+      );
+    } catch {
+    }
   }
   async retirePeriod(obligationId, accountId, tables, signal) {
     const rowStorage = tables.has("adcp_reporting_row_sets");
@@ -1711,14 +1852,21 @@ ${managedDueArm}       )
   async sweepRowWriteIntents(input = {}) {
     const limit = input.limit ?? 100;
     positiveInteger(limit, "limit");
+    const overdueAfter = input.overdueAfterSeconds ?? 24 * 3600;
+    positiveInteger(overdueAfter, "overdueAfterSeconds");
     const tables = await this.optionalTables();
-    if (!tables.has("adcp_reporting_row_write_intents")) return { swept: 0, objectsDeleted: 0, failed: 0 };
+    if (!tables.has("adcp_reporting_row_write_intents")) {
+      return { swept: 0, objectsDeleted: 0, failed: 0, skippedUnconfigured: 0, deferred: 0, overdue: 0 };
+    }
+    const configured = this.rowStorage.objectBindingIds();
+    const due = `($1::text IS NULL OR account_id = $1) AND (state = 'sweeping' OR expires_at <= clock_timestamp())`;
     const expired = await this.query(
       `SELECT row_binding_id, account_id, row_set_id, content_sha256 FROM adcp_reporting_row_write_intents
-        WHERE ($2::text IS NULL OR account_id = $2)
-          AND (state = 'sweeping' OR expires_at <= clock_timestamp())
-        ORDER BY expires_at LIMIT $1`,
-      [limit, input.account_id ?? null]
+        WHERE ${due}
+          AND (next_sweep_at IS NULL OR next_sweep_at <= clock_timestamp())
+          AND (row_binding_id = ANY($2::text[]) OR created_objects = '[]'::jsonb)
+        ORDER BY sweep_attempts, expires_at LIMIT $3`,
+      [input.account_id ?? null, configured, limit]
     );
     let swept = 0;
     let objectsDeleted = 0;
@@ -1751,9 +1899,34 @@ ${managedDueArm}       )
         objectsDeleted += deleted;
       } catch {
         failed += 1;
+        if (!input.signal?.aborted) {
+          await this.query(
+            `UPDATE adcp_reporting_row_write_intents
+                SET sweep_attempts = sweep_attempts + 1,
+                    next_sweep_at = clock_timestamp() + ${backoffIntervalSql("sweep_attempts + 1")}
+              WHERE row_binding_id = $1 AND row_set_id = $2 AND content_sha256 = $3`,
+            key
+          ).catch(() => void 0);
+        }
       }
     }
-    return { swept, objectsDeleted, failed };
+    const backlog = (await this.query(
+      `SELECT count(*) FILTER (WHERE row_binding_id <> ALL($2::text[]) AND created_objects <> '[]'::jsonb) AS skipped,
+                count(*) FILTER (WHERE (row_binding_id = ANY($2::text[]) OR created_objects = '[]'::jsonb)
+                                   AND next_sweep_at > clock_timestamp()) AS deferred,
+                count(*) FILTER (WHERE expires_at <= clock_timestamp() - ($3::integer * INTERVAL '1 second')) AS overdue
+           FROM adcp_reporting_row_write_intents
+          WHERE ${due}`,
+      [input.account_id ?? null, configured, overdueAfter]
+    )).rows[0];
+    return {
+      swept,
+      objectsDeleted,
+      failed,
+      skippedUnconfigured: Number(backlog.skipped),
+      deferred: Number(backlog.deferred),
+      overdue: Number(backlog.overdue)
+    };
   }
   /**
    * Delete external row objects, skipping any object another row set still references.
@@ -2738,12 +2911,18 @@ ${managedDueArm}       )
               const obligationRevisions = revisions.filter(
                 (item) => item.reporting_obligation_id === value.reporting_obligation_id
               );
-              const sellerHealth = (0, import_health.projectReportingObligationHealthV1)(
+              const coreProjection = (0, import_health.projectReportingObligationHealthV1)(
                 value,
                 obligationRevisions,
                 ledgerAsOf,
                 (0, import_coverage.reportingLedgerScopeClosed)(query, ledgerAsOf, ledgerCoverage.complete)
-              ).health;
+              );
+              const sellerHealth = (0, import_health.projectReportingUnreadableRevisionHealthV1)(
+                value,
+                obligationRevisions,
+                issues,
+                coreProjection.health
+              );
               const statuses = consumerStatusProjection.filter((status) => statusMatchesObligation(status, value));
               const leaf = currentConsumerStatus(statuses);
               const mismatch = (0, import_health.projectReportingConsumerStatusMismatchV1)(
@@ -2754,12 +2933,7 @@ ${managedDueArm}       )
                 ledgerAsOf,
                 this.consumerMismatchEscalation
               );
-              const baseProjection = (0, import_health.projectReportingObligationHealthV1)(
-                value,
-                obligationRevisions,
-                ledgerAsOf,
-                (0, import_coverage.reportingLedgerScopeClosed)(query, ledgerAsOf, ledgerCoverage.complete)
-              );
+              const baseProjection = { ...coreProjection, health: sellerHealth };
               const managed = (0, import_handler.projectManagedDelivery)({
                 obligation: value,
                 binding: managedBindings.find((binding) => binding.configurationId === value.configurationId),
@@ -3798,7 +3972,7 @@ ${managedDueArm}       )
           releaseError = rollbackCause instanceof Error ? rollbackCause : new Error("Reporting ledger rollback failed");
         }
       }
-      if (error instanceof ReportingLedgerLeaseLostError || error instanceof ReportingLedgerContinuityError || error instanceof ReportingLedgerPeriodRetiredError || error instanceof import_types.ReportingLedgerSnapshotUnavailableError || error instanceof import_types2.ReportingConsumerStatusConflictError || (0, import_row_storage.isReportingRowStoreError)(error)) {
+      if (error instanceof ReportingLedgerLeaseLostError || error instanceof ReportingLedgerContinuityError || error instanceof import_health.ReportingLedgerIssueIntegrityError || error instanceof ReportingLedgerPeriodRetiredError || error instanceof import_types.ReportingLedgerSnapshotUnavailableError || error instanceof import_types2.ReportingConsumerStatusConflictError || (0, import_row_storage.isReportingRowStoreError)(error)) {
         throw error;
       }
       throw new Error("PostgresReportingLedgerStore transaction failed", { cause: error });