@adcp/sdk 15.8.1 → 16.0.0-beta.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");
@@ -444,9 +469,11 @@ class PostgresReportingLedgerStore {
     );
   }
   /**
-   * Throws `INVALID_INPUT` when any configured object row binding's key template omits
-   * `{revision_key}`, which makes snapshot compaction unsafe (see `compactSupersededSnapshots`).
-   * Called by `compactSupersededSnapshots` and by service construction when compaction is enabled.
+   * Defense in depth for snapshot compaction (see `compactSupersededSnapshots`): throws `INVALID_INPUT`
+   * if a writable object row binding's key template omits `{revision_key}`. Every such binding is
+   * already refused when the store is configured, so this only guards a configuration changed after
+   * construction; `readOnly` bindings are skipped. Called by `compactSupersededSnapshots` and by
+   * service construction when compaction is enabled.
    */
   assertCompactionSafeRowBindings() {
     this.rowStorage.assertCompactionSafeKeyTemplates();
@@ -833,6 +860,7 @@ ${managedDueArm}       )
       rows: revision.rows,
       finality: revision.finality,
       periodStart: lease.obligation.period.start,
+      sourceTimezone: lease.obligation.period.sourceTimezone,
       binding: revision.binding,
       controlTotals: revision.wireRevision.control_totals
     }) : void 0;
@@ -991,6 +1019,7 @@ ${managedDueArm}       )
       obligationId: adjustment.reporting_obligation_id,
       rows: adjustment.rows,
       periodStart: lease.obligation.period.start,
+      sourceTimezone: lease.obligation.period.sourceTimezone,
       binding: adjustment.binding
     }) : void 0;
     const upload = prepared?.binding.kind === "object" ? await this.uploadRowSetUnlessCommitted(prepared, lease, "adcp_reporting_adjustments", "adjustment_id") : void 0;
@@ -1155,9 +1184,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 +1207,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 +1217,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 +1242,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 +1255,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 +1276,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 +1305,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 +1456,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 +1478,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 +1495,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");
@@ -1427,16 +1574,16 @@ ${managedDueArm}       )
     );
     if (rowStorage) {
       const objects = await this.query(
-        `SELECT DISTINCT row_set.row_binding_id, chunk.object_key, chunk.native_version
+        `SELECT DISTINCT row_set.row_binding_id, chunk.object_ref, chunk.native_version_ref
            FROM adcp_reporting_row_chunks chunk
            JOIN adcp_reporting_row_sets row_set ON row_set.row_set_id = chunk.row_set_id
-          WHERE chunk.obligation_id = $1 AND chunk.object_key IS NOT NULL`,
+          WHERE chunk.obligation_id = $1 AND chunk.object_ref IS NOT NULL`,
         [obligationId]
       );
       const byBinding = /* @__PURE__ */ new Map();
       for (const row of objects.rows) {
         const list = byBinding.get(row.row_binding_id) ?? [];
-        list.push({ objectKey: row.object_key, nativeVersion: row.native_version });
+        list.push({ objectRef: row.object_ref, nativeVersionRef: row.native_version_ref });
         byBinding.set(row.row_binding_id, list);
       }
       for (const [bindingId, list] of byBinding) {
@@ -1657,15 +1804,15 @@ ${managedDueArm}       )
     );
     if (binding.rows.length === 0) return false;
     const objects = await this.query(
-      `SELECT DISTINCT chunk.object_key, chunk.native_version
+      `SELECT DISTINCT chunk.object_ref, chunk.native_version_ref
          FROM adcp_reporting_row_chunks chunk
-        WHERE chunk.row_set_id = $1 AND chunk.object_key IS NOT NULL`,
+        WHERE chunk.row_set_id = $1 AND chunk.object_ref IS NOT NULL`,
       [revisionId]
     );
     if (objects.rows.length > 0) {
       await this.deleteUnreferencedObjects(
         binding.rows[0].row_binding_id,
-        objects.rows.map((row) => ({ objectKey: row.object_key, nativeVersion: row.native_version })),
+        objects.rows.map((row) => ({ objectRef: row.object_ref, nativeVersionRef: row.native_version_ref })),
         { rowSetId: revisionId },
         signal
       );
@@ -1673,10 +1820,10 @@ ${managedDueArm}       )
     await this.transaction(
       async (client) => {
         const dropped = await client.query(
-          `DELETE FROM adcp_reporting_row_chunks WHERE row_set_id = $1 RETURNING sha256, object_key`,
+          `DELETE FROM adcp_reporting_row_chunks WHERE row_set_id = $1 RETURNING sha256, object_ref`,
           [revisionId]
         );
-        const bodies = [...new Set(dropped.rows.filter((row) => row.object_key === null).map((row) => row.sha256))];
+        const bodies = [...new Set(dropped.rows.filter((row) => row.object_ref === null).map((row) => row.sha256))];
         if (bodies.length > 0) {
           await client.query(
             `DELETE FROM adcp_reporting_chunk_bodies body
@@ -1684,7 +1831,7 @@ ${managedDueArm}       )
                 AND NOT EXISTS (
                   SELECT 1 FROM adcp_reporting_row_chunks other
                    WHERE other.account_id = body.account_id AND other.obligation_id = body.obligation_id
-                     AND other.sha256 = body.sha256 AND other.object_key IS NULL
+                     AND other.sha256 = body.sha256 AND other.object_ref IS NULL
                 )`,
             [accountId, obligationId, bodies]
           );
@@ -1710,14 +1857,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;
@@ -1735,7 +1889,12 @@ ${managedDueArm}       )
                 RETURNING created_objects`,
               key
             );
-            return updated.rows[0]?.created_objects;
+            return updated.rows[0]?.created_objects.map((object) => ({
+              objectRef: object.object_ref ?? object.objectKey,
+              nativeVersionRef: object.native_version_ref ?? object.nativeVersion
+            })).filter(
+              (object) => typeof object.objectRef === "string" && typeof object.nativeVersionRef === "string"
+            );
           },
           { preBeginAdvisoryLock: accountLock(intent.account_id) }
         );
@@ -1750,16 +1909,41 @@ ${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.
    *
-   * A custom `keyTemplate` need only include `{content_sha256}` and `{chunk_index}`, so row sets
-   * from different obligations or accounts with identical chunk content can share one object (a
-   * create-only write adopts an existing object). An object is therefore deleted only when no
+   * Object keys are unique per row set (every writable template includes `{revision_key}`), but header-only
+   * revisions share chunks within an obligation and rows written under an older template can name one
+   * object from several row sets. An object is therefore deleted only when no
    * chunk of a live (or unavailable) row set outside this operation references the same binding,
    * key and native version, and no other open write intent created it. Row sets already `pruning`
    * or `pruned` do not count: their own operation deletes the object, and counting them would let
@@ -1781,27 +1965,30 @@ ${managedDueArm}       )
       signal?.throwIfAborted();
       const removed = await this.transaction(async (client) => {
         await client.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [
-          objectLock(bindingId, object.objectKey)
+          objectLock(bindingId, object.objectRef)
         ]);
         const referenced = await client.query(
           `(SELECT 1 FROM adcp_reporting_row_chunks chunk
               JOIN adcp_reporting_row_sets row_set ON row_set.row_set_id = chunk.row_set_id
-             WHERE row_set.row_binding_id = $1 AND chunk.object_key = $2 AND chunk.native_version = $3
+             WHERE row_set.row_binding_id = $1 AND chunk.object_ref = $2 AND chunk.native_version_ref = $3
                AND row_set.rows_state IN ('live', 'unavailable')
                AND ($4::text IS NULL OR chunk.obligation_id <> $4)
                AND ($5::text IS NULL OR chunk.row_set_id <> $5)
              LIMIT 1)
            UNION ALL
            (SELECT 1 FROM adcp_reporting_row_write_intents intent
-             WHERE intent.row_binding_id = $1 AND intent.state = 'open' AND intent.created_objects @> $6::jsonb
+             WHERE intent.row_binding_id = $1 AND intent.state = 'open'
+               AND (intent.created_objects @> $6::jsonb OR intent.created_objects @> $7::jsonb)
              LIMIT 1)`,
           [
             bindingId,
-            object.objectKey,
-            object.nativeVersion,
+            object.objectRef,
+            object.nativeVersionRef,
             scope.obligationId ?? null,
             scope.rowSetId ?? null,
-            JSON.stringify([{ objectKey: object.objectKey, nativeVersion: object.nativeVersion }])
+            JSON.stringify([{ object_ref: object.objectRef, native_version_ref: object.nativeVersionRef }]),
+            // An older writer still running during a rolling upgrade records the pre-alignment keys.
+            JSON.stringify([{ objectKey: object.objectRef, nativeVersion: object.nativeVersionRef }])
           ]
         );
         if (referenced.rows.length > 0) return false;
@@ -1887,7 +2074,11 @@ ${managedDueArm}       )
             SET created_objects = created_objects || $5::jsonb
           WHERE row_binding_id = $1 AND row_set_id = $2 AND content_sha256 = $3
             AND owner_token = $4 AND state = 'open'`,
-        [...intentKey, ownerToken, JSON.stringify([object])]
+        [
+          ...intentKey,
+          ownerToken,
+          JSON.stringify([{ object_ref: object.objectRef, native_version_ref: object.nativeVersionRef }])
+        ]
       );
       if (recorded.rowCount !== 1) {
         throw new ReportingRowStoreError("STATE_UNAVAILABLE", "the row upload intent was taken over or swept");
@@ -1923,10 +2114,10 @@ ${managedDueArm}       )
       }
     }
     if (!upload.sharedFrom) {
-      const adopted = upload.locators.filter((locator) => !locator.created).sort((left, right) => left.objectKey < right.objectKey ? -1 : left.objectKey > right.objectKey ? 1 : 0);
+      const adopted = upload.locators.filter((locator) => !locator.created).sort((left, right) => left.objectRef < right.objectRef ? -1 : left.objectRef > right.objectRef ? 1 : 0);
       for (const locator of adopted) {
         await client.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [
-          objectLock(prepared.bindingId, locator.objectKey)
+          objectLock(prepared.bindingId, locator.objectRef)
         ]);
       }
       if (adopted.length > 0) await this.rowStorage.assertObjectsPresent(prepared.bindingId, adopted);
@@ -2737,12 +2928,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 +2950,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 +3989,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 });
@@ -4119,8 +4311,8 @@ function rfc3339Microseconds(expression) {
 function accountLock(accountId) {
   return `adcp-reporting-account:${accountId}`;
 }
-function objectLock(bindingId, objectKey) {
-  return `adcp-reporting-object:${bindingId}:${objectKey}`;
+function objectLock(bindingId, objectRef) {
+  return `adcp-reporting-object:${bindingId}:${objectRef}`;
 }
 async function resolveStoredFinalityBaseline(transaction, obligationId) {
   const latest = await transaction.query(