@adcp/sdk 15.8.1 → 15.9.1

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

@@ -11,7 +11,9 @@ import {
 import {
   assertReportingConsumerMismatchEscalation,
   projectReportingConsumerStatusMismatchV1,
-  projectReportingObligationHealthV1
+  projectReportingObligationHealthV1,
+  projectReportingUnreadableRevisionHealthV1,
+  ReportingLedgerIssueIntegrityError
 } from "./health.mjs";
 import { compareReportingInstants } from "./instant.mjs";
 import {
@@ -312,6 +314,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 = `
@@ -356,6 +377,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");
@@ -1155,9 +1180,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");
@@ -1166,7 +1203,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 : 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`,
@@ -1176,10 +1213,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 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 ReportingChangeCursorExpiredError(
+          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,
@@ -1190,7 +1238,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]
@@ -1202,6 +1251,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 ? encodeReportingChangeCursorV1({ v: 1, account, seq: last.seq, ...account === null ? { xid: last.xid } : {} }) : input.cursor ?? encodeReportingChangeCursorV1(position);
     return {
@@ -1218,8 +1272,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 {
@@ -1229,14 +1301,45 @@ ${managedDueArm}       )
       throw new RangeError("feed consumer cursor is invalid");
     }
     const decoded = 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
@@ -1349,11 +1452,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()
@@ -1368,8 +1474,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]
     );
@@ -1383,14 +1491,49 @@ ${managedDueArm}       )
         retired += 1;
       } catch (error) {
         if (error instanceof ReportingLedgerPeriodRetiredError) continue;
+        const cause = isReportingRowStoreError(error) ? error.code : error instanceof Error ? error.name : "Error";
         failed.push(candidate.obligation_id);
-        failures.push({
-          reporting_obligation_id: candidate.obligation_id,
-          cause: 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");
@@ -1710,14 +1853,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;
@@ -1750,9 +1900,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.
@@ -2737,12 +2912,18 @@ ${managedDueArm}       )
               const obligationRevisions = revisions.filter(
                 (item) => item.reporting_obligation_id === value.reporting_obligation_id
               );
-              const sellerHealth = projectReportingObligationHealthV1(
+              const coreProjection = projectReportingObligationHealthV1(
                 value,
                 obligationRevisions,
                 ledgerAsOf,
                 reportingLedgerScopeClosed(query, ledgerAsOf, ledgerCoverage.complete)
-              ).health;
+              );
+              const sellerHealth = projectReportingUnreadableRevisionHealthV1(
+                value,
+                obligationRevisions,
+                issues,
+                coreProjection.health
+              );
               const statuses = consumerStatusProjection.filter((status) => statusMatchesObligation(status, value));
               const leaf = currentConsumerStatus(statuses);
               const mismatch = projectReportingConsumerStatusMismatchV1(
@@ -2753,12 +2934,7 @@ ${managedDueArm}       )
                 ledgerAsOf,
                 this.consumerMismatchEscalation
               );
-              const baseProjection = projectReportingObligationHealthV1(
-                value,
-                obligationRevisions,
-                ledgerAsOf,
-                reportingLedgerScopeClosed(query, ledgerAsOf, ledgerCoverage.complete)
-              );
+              const baseProjection = { ...coreProjection, health: sellerHealth };
               const managed = projectManagedDelivery({
                 obligation: value,
                 binding: managedBindings.find((binding) => binding.configurationId === value.configurationId),
@@ -3797,7 +3973,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 ReportingLedgerSnapshotUnavailableError || error instanceof ReportingConsumerStatusConflictError || isReportingRowStoreError(error)) {
+      if (error instanceof ReportingLedgerLeaseLostError || error instanceof ReportingLedgerContinuityError || error instanceof ReportingLedgerIssueIntegrityError || error instanceof ReportingLedgerPeriodRetiredError || error instanceof ReportingLedgerSnapshotUnavailableError || error instanceof ReportingConsumerStatusConflictError || isReportingRowStoreError(error)) {
         throw error;
       }
       throw new Error("PostgresReportingLedgerStore transaction failed", { cause: error });

package/dist/lib/reporting/ledger/row-storage-migration.js

@@ -134,6 +134,22 @@ CREATE TABLE IF NOT EXISTS adcp_reporting_row_write_intents (
 CREATE INDEX IF NOT EXISTS adcp_reporting_row_write_intents_expiry
   ON adcp_reporting_row_write_intents (expires_at, account_id)
   WHERE state = 'open';
+-- Sweep retry state. An intent whose sweep fails backs off instead of holding
+-- 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 every upload.
+DO $intent_retry$
+DECLARE
+  intents regclass := to_regclass('adcp_reporting_row_write_intents');
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_attribute WHERE attrelid = intents AND attname = 'sweep_attempts' AND NOT attisdropped) THEN
+    ALTER TABLE adcp_reporting_row_write_intents ADD COLUMN sweep_attempts INTEGER NOT NULL DEFAULT 0;
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_attribute WHERE attrelid = intents AND attname = 'next_sweep_at' AND NOT attisdropped) THEN
+    ALTER TABLE adcp_reporting_row_write_intents ADD COLUMN next_sweep_at TIMESTAMPTZ;
+  END IF;
+END
+$intent_retry$;
 
 CREATE OR REPLACE FUNCTION adcp_reporting_row_storage_immutable() RETURNS trigger
 LANGUAGE plpgsql AS $immutable$

package/dist/lib/reporting/ledger/row-storage-migration.mjs

@@ -109,6 +109,22 @@ CREATE TABLE IF NOT EXISTS adcp_reporting_row_write_intents (
 CREATE INDEX IF NOT EXISTS adcp_reporting_row_write_intents_expiry
   ON adcp_reporting_row_write_intents (expires_at, account_id)
   WHERE state = 'open';
+-- Sweep retry state. An intent whose sweep fails backs off instead of holding
+-- 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 every upload.
+DO $intent_retry$
+DECLARE
+  intents regclass := to_regclass('adcp_reporting_row_write_intents');
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_attribute WHERE attrelid = intents AND attname = 'sweep_attempts' AND NOT attisdropped) THEN
+    ALTER TABLE adcp_reporting_row_write_intents ADD COLUMN sweep_attempts INTEGER NOT NULL DEFAULT 0;
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_attribute WHERE attrelid = intents AND attname = 'next_sweep_at' AND NOT attisdropped) THEN
+    ALTER TABLE adcp_reporting_row_write_intents ADD COLUMN next_sweep_at TIMESTAMPTZ;
+  END IF;
+END
+$intent_retry$;
 
 CREATE OR REPLACE FUNCTION adcp_reporting_row_storage_immutable() RETURNS trigger
 LANGUAGE plpgsql AS $immutable$

package/dist/lib/reporting/ledger/row-storage.d.mts

@@ -164,6 +164,8 @@ export declare class ReportingRowStorageV1 {
      * depth for compaction, the one path that deletes content while the obligation stays live.
      */
     assertCompactionSafeKeyTemplates(): void;
+    /** IDs of the object bindings this host configures, the only ones it can delete objects through. */
+    objectBindingIds(): string[];
     /** Probe the schema and every provider, and register (or verify) every configured binding. Idempotent. */
     ready(): Promise<void>;
     /** Encode rows, prove the chunks reproduce the committed binding, select a binding and plan objects. */

package/dist/lib/reporting/ledger/row-storage.d.ts

@@ -164,6 +164,8 @@ export declare class ReportingRowStorageV1 {
      * depth for compaction, the one path that deletes content while the obligation stays live.
      */
     assertCompactionSafeKeyTemplates(): void;
+    /** IDs of the object bindings this host configures, the only ones it can delete objects through. */
+    objectBindingIds(): string[];
     /** Probe the schema and every provider, and register (or verify) every configured binding. Idempotent. */
     ready(): Promise<void>;
     /** Encode rows, prove the chunks reproduce the committed binding, select a binding and plan objects. */

package/dist/lib/reporting/ledger/row-storage.js

@@ -103,6 +103,10 @@ class ReportingRowStorageV1 {
       );
     }
   }
+  /** IDs of the object bindings this host configures, the only ones it can delete objects through. */
+  objectBindingIds() {
+    return Object.entries(this.bindings).filter(([, binding]) => binding.kind === "object").map(([id]) => id);
+  }
   /** Probe the schema and every provider, and register (or verify) every configured binding. Idempotent. */
   ready() {
     this.readied ??= this.register().catch((error) => {

package/dist/lib/reporting/ledger/row-storage.mjs

@@ -92,6 +92,10 @@ class ReportingRowStorageV1 {
       );
     }
   }
+  /** IDs of the object bindings this host configures, the only ones it can delete objects through. */
+  objectBindingIds() {
+    return Object.entries(this.bindings).filter(([, binding]) => binding.kind === "object").map(([id]) => id);
+  }
   /** Probe the schema and every provider, and register (or verify) every configured binding. Idempotent. */
   ready() {
     this.readied ??= this.register().catch((error) => {

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

@@ -302,7 +302,7 @@ export type ReportingIssueStateV1 = 'open' | 'acknowledged' | 'resolved' | 'waiv
 export interface ReportingLedgerIssueV1 {
     issueId: string;
     reporting_obligation_id: string;
-    code: 'REPORT_OVERDUE' | 'PRODUCTION_FAILED' | 'DELIVERY_FAILED' | 'ACCESS_REQUIRED' | 'CONFIGURATION_REQUIRED' | 'REPORTING_COVERAGE_INCOMPLETE' | 'RESOURCE_EXPIRED' | 'READER_INCOMPATIBLE' | 'HISTORY_UNAVAILABLE' | 'RECEIPT_REQUIRED' | 'RECEIPT_REJECTED' | 'ADJUSTMENT_RECEIPT_REQUIRED' | 'ADJUSTMENT_RECEIPT_REJECTED' | 'CONSUMER_STATUS_MISMATCH';
+    code: 'REPORT_OVERDUE' | 'PRODUCTION_FAILED' | 'DELIVERY_FAILED' | 'ACCESS_REQUIRED' | 'CONFIGURATION_REQUIRED' | 'REPORTING_COVERAGE_INCOMPLETE' | 'RESOURCE_EXPIRED' | 'READER_INCOMPATIBLE' | 'HISTORY_UNAVAILABLE' | 'REVISION_UNREADABLE' | 'RECEIPT_REQUIRED' | 'RECEIPT_REJECTED' | 'ADJUSTMENT_RECEIPT_REQUIRED' | 'ADJUSTMENT_RECEIPT_REJECTED' | 'CONSUMER_STATUS_MISMATCH';
     severity: 'delayed' | 'action_required';
     responsibleParty: 'seller' | 'buyer' | 'provider';
     recommendedAction: 'wait_for_retry' | 'contact_buyer' | 'contact_seller' | 'contact_provider' | 'repair_access' | 'update_configuration' | 'change_reporting_scope' | 'use_supported_reader';
@@ -313,6 +313,8 @@ export interface ReportingLedgerIssueV1 {
      * which is the variant to construct for that code.
      */
     reporting_status_id?: string;
+    /** Affected revision, required for REVISION_UNREADABLE. */
+    reporting_revision_id?: string;
     /**
      * When the seller first observed this logical condition.
      *
@@ -358,6 +360,18 @@ export interface ReportingLedgerIssueV1 {
     observedAt: string;
     resolvedAt?: string;
 }
+/** Seller-attributed unreadability of a previously published revision. */
+export type ReportingLedgerRevisionUnreadableIssueV1 = ReportingLedgerIssueV1 & {
+    code: 'REVISION_UNREADABLE';
+    reporting_revision_id: string;
+    responsibleParty: 'seller';
+} & ({
+    severity: 'delayed';
+    recommendedAction: 'wait_for_retry';
+} | {
+    severity: 'action_required';
+    recommendedAction: 'contact_seller';
+});
 /**
  * Non-secret human escalation path for reporting issues the protocol cannot
  * resolve. Display metadata for an operator, not an AdCP endpoint: agents MUST

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

@@ -302,7 +302,7 @@ export type ReportingIssueStateV1 = 'open' | 'acknowledged' | 'resolved' | 'waiv
 export interface ReportingLedgerIssueV1 {
     issueId: string;
     reporting_obligation_id: string;
-    code: 'REPORT_OVERDUE' | 'PRODUCTION_FAILED' | 'DELIVERY_FAILED' | 'ACCESS_REQUIRED' | 'CONFIGURATION_REQUIRED' | 'REPORTING_COVERAGE_INCOMPLETE' | 'RESOURCE_EXPIRED' | 'READER_INCOMPATIBLE' | 'HISTORY_UNAVAILABLE' | 'RECEIPT_REQUIRED' | 'RECEIPT_REJECTED' | 'ADJUSTMENT_RECEIPT_REQUIRED' | 'ADJUSTMENT_RECEIPT_REJECTED' | 'CONSUMER_STATUS_MISMATCH';
+    code: 'REPORT_OVERDUE' | 'PRODUCTION_FAILED' | 'DELIVERY_FAILED' | 'ACCESS_REQUIRED' | 'CONFIGURATION_REQUIRED' | 'REPORTING_COVERAGE_INCOMPLETE' | 'RESOURCE_EXPIRED' | 'READER_INCOMPATIBLE' | 'HISTORY_UNAVAILABLE' | 'REVISION_UNREADABLE' | 'RECEIPT_REQUIRED' | 'RECEIPT_REJECTED' | 'ADJUSTMENT_RECEIPT_REQUIRED' | 'ADJUSTMENT_RECEIPT_REJECTED' | 'CONSUMER_STATUS_MISMATCH';
     severity: 'delayed' | 'action_required';
     responsibleParty: 'seller' | 'buyer' | 'provider';
     recommendedAction: 'wait_for_retry' | 'contact_buyer' | 'contact_seller' | 'contact_provider' | 'repair_access' | 'update_configuration' | 'change_reporting_scope' | 'use_supported_reader';
@@ -313,6 +313,8 @@ export interface ReportingLedgerIssueV1 {
      * which is the variant to construct for that code.
      */
     reporting_status_id?: string;
+    /** Affected revision, required for REVISION_UNREADABLE. */
+    reporting_revision_id?: string;
     /**
      * When the seller first observed this logical condition.
      *
@@ -358,6 +360,18 @@ export interface ReportingLedgerIssueV1 {
     observedAt: string;
     resolvedAt?: string;
 }
+/** Seller-attributed unreadability of a previously published revision. */
+export type ReportingLedgerRevisionUnreadableIssueV1 = ReportingLedgerIssueV1 & {
+    code: 'REVISION_UNREADABLE';
+    reporting_revision_id: string;
+    responsibleParty: 'seller';
+} & ({
+    severity: 'delayed';
+    recommendedAction: 'wait_for_retry';
+} | {
+    severity: 'action_required';
+    recommendedAction: 'contact_seller';
+});
 /**
  * Non-secret human escalation path for reporting issues the protocol cannot
  * resolve. Display metadata for an operator, not an AdCP endpoint: agents MUST

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

@@ -49,7 +49,19 @@ export declare class ReportingMaintenancePartialFailureError extends Error {
     readonly task: string;
     readonly failedCount: number;
     readonly failedIds: readonly string[];
-    constructor(task: string, failedCount: number, failedIds: readonly string[]);
+    /**
+     * Backlog the task is not reaching: items backing off, items this host cannot
+     * handle, items that have failed persistently. Appended to the message so
+     * `onError` and the logs carry them.
+     */
+    readonly warnings: readonly string[];
+    constructor(task: string, failedCount: number, failedIds: readonly string[], 
+    /**
+     * Backlog the task is not reaching: items backing off, items this host cannot
+     * handle, items that have failed persistently. Appended to the message so
+     * `onError` and the logs carry them.
+     */
+    warnings?: readonly string[]);
 }
 /**
  * Outcome of one maintenance task. A task that resolved but could not process

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

@@ -49,7 +49,19 @@ export declare class ReportingMaintenancePartialFailureError extends Error {
     readonly task: string;
     readonly failedCount: number;
     readonly failedIds: readonly string[];
-    constructor(task: string, failedCount: number, failedIds: readonly string[]);
+    /**
+     * Backlog the task is not reaching: items backing off, items this host cannot
+     * handle, items that have failed persistently. Appended to the message so
+     * `onError` and the logs carry them.
+     */
+    readonly warnings: readonly string[];
+    constructor(task: string, failedCount: number, failedIds: readonly string[], 
+    /**
+     * Backlog the task is not reaching: items backing off, items this host cannot
+     * handle, items that have failed persistently. Appended to the message so
+     * `onError` and the logs carry them.
+     */
+    warnings?: readonly string[]);
 }
 /**
  * Outcome of one maintenance task. A task that resolved but could not process