@adcp/sdk 15.4.0 → 15.5.0

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

@@ -25,6 +25,17 @@ import {
 import { ReportingConsumerStatusConflictError } from "./types.mjs";
 import { moreSevereReportingHealthV1, projectManagedDelivery } from "./handler.mjs";
 import { reportingCanonicalAdjustmentSha256V1 } from "./producer.mjs";
+import {
+  ReportingChangeCursorExpiredError,
+  decodeReportingChangeCursorV1,
+  encodeReportingChangeCursorV1
+} from "./change-feed.mjs";
+import {
+  ReportingRowStorageV1,
+  ReportingRowStoreError,
+  isReportingRowStoreError,
+  reportingRowWriteIntentIdV1
+} from "./row-storage.mjs";
 import { isFrozenCalendarRulesMismatch, reportingPeriodSchedule } from "./schedule.mjs";
 import {
   normalizeReportingConsumerStatusIdsV1,
@@ -278,6 +289,29 @@ CREATE TABLE IF NOT EXISTS adcp_reporting_checkpoints (
 );
 CREATE INDEX IF NOT EXISTS adcp_reporting_checkpoints_expiry
   ON adcp_reporting_checkpoints (expires_at);
+
+-- A retired period keeps one compact record: it refuses replays that would
+-- resurrect the period and preserves the audit conclusion after the period's
+-- ledger records are deleted.
+CREATE TABLE IF NOT EXISTS adcp_reporting_obligation_tombstones (
+  obligation_id TEXT PRIMARY KEY,
+  account_id TEXT NOT NULL,
+  configuration_id TEXT NOT NULL,
+  period_ordinal BIGINT NOT NULL,
+  period_start TIMESTAMPTZ NOT NULL,
+  period_end TIMESTAMPTZ NOT NULL,
+  state TEXT NOT NULL CHECK (state IN ('retiring', 'retired')),
+  final_revision_id TEXT,
+  final_content_sha256 TEXT,
+  revision_count INTEGER NOT NULL CHECK (revision_count >= 0),
+  adjustment_count INTEGER NOT NULL CHECK (adjustment_count >= 0),
+  retiring_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
+  retired_at TIMESTAMPTZ,
+  UNIQUE (configuration_id, period_ordinal),
+  CHECK ((state = 'retired') = (retired_at IS NOT NULL))
+);
+CREATE INDEX IF NOT EXISTS adcp_reporting_obligation_tombstones_account
+  ON adcp_reporting_obligation_tombstones (account_id, configuration_id, period_ordinal);
 `.trim();
 const REPORTING_LEDGER_FINALITY_FENCE_CONSTRAINT = "adcp_reporting_transitions_finality_recorded";
 const REPORTING_LEDGER_FINALITY_WRITER_FENCE_MIGRATION = `
@@ -310,6 +344,12 @@ class ReportingLedgerLeaseLostError extends Error {
     this.name = "ReportingLedgerLeaseLostError";
   }
 }
+class ReportingLedgerPeriodRetiredError extends Error {
+  constructor(message = "Reporting obligation period was retired by retention") {
+    super(message);
+    this.name = "ReportingLedgerPeriodRetiredError";
+  }
+}
 class ReportingLedgerContinuityError extends Error {
   constructor(message = "Reporting ledger revision continuity invariant failed") {
     super(message);
@@ -362,6 +402,9 @@ class PostgresReportingLedgerStore {
     this.consumerMismatchEscalation = assertReportingConsumerMismatchEscalation(options.consumerMismatchEscalation);
     this.notificationActivityPort = options.notificationActivityPort;
     this.transactionalNotificationActivity = options.notificationActivityPort !== void 0;
+    this.rowStorage = new ReportingRowStorageV1(pool, typeof options.rowStorage === "object" ? options.rowStorage : {});
+    this.rowStorageWrites = options.rowStorage !== void 0 && options.rowStorage !== false;
+    this.changeFeed = options.changeFeed === true;
   }
   pool;
   /**
@@ -377,6 +420,119 @@ class PostgresReportingLedgerStore {
   obligatedConsumers;
   transactionalNotificationActivity;
   notificationActivityPort;
+  rowStorage;
+  rowStorageWrites;
+  changeFeed;
+  /** Append one host change-feed row inside the caller's account-locked transaction. */
+  async appendChange(client, kind, accountId, recordId, obligationId) {
+    if (!this.changeFeed) return;
+    await client.query(
+      `INSERT INTO adcp_reporting_changes (account_id, record_kind, record_id, obligation_id) VALUES ($1, $2, $3, $4)`,
+      [accountId, kind, recordId, obligationId]
+    );
+  }
+  /** Probe and register row storage when enabled. Safe to call repeatedly. */
+  async readyRowStorage() {
+    if (this.rowStorageWrites) await this.rowStorage.ready();
+  }
+  /**
+   * Move legacy inline revision and adjustment rows into row storage, a
+   * bounded batch at a time. Each row set is re-encoded, proven to reproduce
+   * its committed binding, written, and only then removed from the ledger
+   * document, in one transaction under the account lock. A document whose
+   * rows do not reproduce its binding is never rewritten: it is reported in
+   * `quarantined` and left inline. Pass the returned `cursor` back to resume
+   * after the last examined document; it is absent once every candidate has
+   * been examined. Reclaiming the freed space needs `VACUUM FULL` or an online
+   * repack.
+   */
+  async migrateInlineRows(input = {}) {
+    if (!this.rowStorageWrites) throw new Error("migrateInlineRows requires rowStorage");
+    const limit = input.limit ?? 100;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1e4) {
+      throw new RangeError("migrateInlineRows limit must be between 1 and 10000");
+    }
+    let after;
+    if (input.cursor !== void 0) {
+      try {
+        const parsed = JSON.parse(Buffer.from(input.cursor, "base64url").toString("utf8"));
+        if (typeof parsed.at !== "string" || typeof parsed.id !== "string") throw new Error("invalid");
+        after = { at: parsed.at, id: parsed.id };
+      } catch {
+        throw new RangeError("migrateInlineRows cursor is invalid");
+      }
+    }
+    await this.rowStorage.ready();
+    const candidates = await this.query(
+      `SELECT kind, id, account_id, to_char(recorded_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"') AS at
+         FROM (
+           SELECT 'revision' AS kind, revision.revision_id AS id, obligation.account_id, revision.recorded_at
+             FROM adcp_reporting_revisions revision
+             JOIN adcp_reporting_obligations obligation ON obligation.obligation_id = revision.obligation_id
+            WHERE revision.data ? 'rows' AND ($2::text IS NULL OR obligation.account_id = $2)
+           UNION ALL
+           SELECT 'adjustment', adjustment.adjustment_id, obligation.account_id, adjustment.recorded_at
+             FROM adcp_reporting_adjustments adjustment
+             JOIN adcp_reporting_obligations obligation ON obligation.obligation_id = adjustment.obligation_id
+            WHERE adjustment.data ? 'rows' AND ($2::text IS NULL OR obligation.account_id = $2)
+         ) inline_rows
+        WHERE $3::timestamptz IS NULL OR (recorded_at, id) > ($3::timestamptz, $4::text)
+        ORDER BY recorded_at, id
+        LIMIT $1`,
+      [limit + 1, input.account_id ?? null, after?.at ?? null, after?.id ?? null]
+    );
+    let migrated = 0;
+    const quarantined = [];
+    for (const candidate of candidates.rows.slice(0, limit)) {
+      input.signal?.throwIfAborted();
+      const table = candidate.kind === "revision" ? "adcp_reporting_revisions" : "adcp_reporting_adjustments";
+      const idColumn = candidate.kind === "revision" ? "revision_id" : "adjustment_id";
+      const outcome = await this.transaction(
+        async (client) => {
+          const locked = await client.query(
+            `SELECT data FROM ${table} WHERE ${idColumn} = $1 AND data ? 'rows' FOR UPDATE`,
+            [candidate.id]
+          );
+          const document = locked.rows[0]?.data;
+          if (!document) return "skipped";
+          let prepared;
+          try {
+            prepared = await this.rowStorage.prepare({
+              rowSetId: candidate.id,
+              rowSetKind: candidate.kind,
+              accountId: candidate.account_id,
+              obligationId: document.reporting_obligation_id,
+              rows: document.rows,
+              ...candidate.kind === "revision" ? { finality: document.finality, controlTotals: document.wireRevision.control_totals } : {},
+              binding: document.binding,
+              ...input.bindingId ? { bindingId: input.bindingId } : {}
+            });
+          } catch (error) {
+            if (isReportingRowStoreError(error) && error.code === "INVALID_INPUT") return "quarantined";
+            throw error;
+          }
+          if (prepared.binding.kind !== "postgres") {
+            throw new ReportingRowStoreError(
+              "INVALID_INPUT",
+              "migrateInlineRows writes PostgreSQL-kind row sets; select a postgres binding for migrated rows"
+            );
+          }
+          await this.rowStorage.writeInTransaction(client, prepared);
+          await client.query(`UPDATE ${table} SET data = data - 'rows' WHERE ${idColumn} = $1`, [candidate.id]);
+          return "migrated";
+        },
+        { preBeginAdvisoryLock: accountLock(candidate.account_id) }
+      );
+      if (outcome === "migrated") migrated += 1;
+      if (outcome === "quarantined") quarantined.push(candidate.id);
+    }
+    const last = candidates.rows.length > limit ? candidates.rows[limit - 1] : void 0;
+    return {
+      migrated,
+      quarantined,
+      ...last ? { cursor: Buffer.from(JSON.stringify({ at: last.at, id: last.id }), "utf8").toString("base64url") } : {}
+    };
+  }
   async putConfiguration(configuration) {
     return this.transaction(
       async (client) => {
@@ -433,11 +589,20 @@ class PostgresReportingLedgerStore {
     return result.rows.map((row) => clone(row.data));
   }
   async putObligation(obligation) {
+    const retired = await this.query(
+      `SELECT 1 FROM adcp_reporting_obligation_tombstones WHERE configuration_id = $1 AND period_ordinal = $2`,
+      [obligation.configurationId, obligation.periodOrdinal]
+    );
+    if (retired.rows.length > 0) throw new ReportingLedgerPeriodRetiredError();
     return this.putImmutable(
       `INSERT INTO adcp_reporting_obligations
          (obligation_id, configuration_id, account_id, period_ordinal, period_start, period_end,
           next_attempt_at, state, semantic_fingerprint, data, created_at)
-       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10::jsonb, clock_timestamp())
+       SELECT $1, $2, $3, $4, $5, $6, $7, $8, $9, $10::jsonb, clock_timestamp()
+        WHERE NOT EXISTS (
+          SELECT 1 FROM adcp_reporting_obligation_tombstones
+           WHERE configuration_id = $2 AND period_ordinal = $4
+        )
        ON CONFLICT DO NOTHING RETURNING data`,
       [
         obligation.reporting_obligation_id,
@@ -456,7 +621,16 @@ class PostgresReportingLedgerStore {
       [obligation.configurationId, obligation.periodOrdinal],
       obligation,
       (value) => value.semanticFingerprint,
-      accountLock(obligation.account.account_id)
+      accountLock(obligation.account.account_id),
+      void 0,
+      void 0,
+      this.changeFeed ? (client) => this.appendChange(
+        client,
+        "obligation",
+        obligation.account.account_id,
+        obligation.reporting_obligation_id,
+        obligation.reporting_obligation_id
+      ) : void 0
     );
   }
   async getObligation(id, account_id) {
@@ -466,6 +640,18 @@ class PostgresReportingLedgerStore {
       [id, account_id ?? null]
     );
   }
+  /** Periods retired by retention; planners treat them as already covered. */
+  async listRetiredObligationOrdinals(account_id) {
+    const result = await this.query(
+      `SELECT configuration_id, period_ordinal FROM adcp_reporting_obligation_tombstones
+        WHERE ($1::text IS NULL OR account_id = $1) ORDER BY configuration_id, period_ordinal`,
+      [account_id ?? null]
+    );
+    return result.rows.map((row) => ({
+      configurationId: row.configuration_id,
+      periodOrdinal: Number(row.period_ordinal)
+    }));
+  }
   async listObligations(account_id) {
     const result = await this.query(
       `SELECT data FROM adcp_reporting_obligations
@@ -544,6 +730,13 @@ ${managedDueArm}       )
           ]
         );
         if (result.rowCount !== 1) throw new ReportingLedgerLeaseLostError();
+        await this.appendChange(
+          client,
+          "obligation",
+          lease.obligation.account.account_id,
+          obligation.reporting_obligation_id,
+          obligation.reporting_obligation_id
+        );
         if (issue) {
           if (issue.reporting_obligation_id !== obligation.reporting_obligation_id) {
             throw new Error("Reporting issue must belong to the leased obligation");
@@ -612,7 +805,20 @@ ${managedDueArm}       )
   async commitRevision(revision, lease) {
     assertLeaseTarget(revision.reporting_obligation_id, lease);
     validateRevisionBinding(revision);
-    return this.putImmutable(
+    const prepared = this.rowStorageWrites ? await this.rowStorage.prepare({
+      rowSetId: revision.reporting_revision_id,
+      rowSetKind: "revision",
+      accountId: lease.obligation.account.account_id,
+      obligationId: revision.reporting_obligation_id,
+      rows: revision.rows,
+      finality: revision.finality,
+      periodStart: lease.obligation.period.start,
+      binding: revision.binding,
+      controlTotals: revision.wireRevision.control_totals
+    }) : void 0;
+    const upload = prepared?.binding.kind === "object" ? await this.uploadRowSetUnlessCommitted(prepared, lease, "adcp_reporting_revisions", "revision_id") : void 0;
+    const port = this.notificationActivityPort?.recordLedgerChanged ? this.notificationActivityPort : void 0;
+    const result = await this.putImmutable(
       `WITH leased_obligation AS (
          SELECT * FROM adcp_reporting_obligations obligation
           WHERE obligation.obligation_id = $2
@@ -649,7 +855,7 @@ ${managedDueArm}       )
         revision.kind,
         revision.supersedes_reporting_revision_id ?? null,
         revision.binding.sha256,
-        JSON.stringify(revision),
+        JSON.stringify(prepared ? withoutRows(revision) : revision),
         lease.owner,
         lease.generation
       ],
@@ -664,19 +870,31 @@ ${managedDueArm}       )
         generation: lease.generation
       },
       revisionLegacyCanonicalDigestReplay,
-      this.notificationActivityPort?.recordLedgerChanged ? (client, committed) => this.notificationActivityPort.recordLedgerChanged(
-        { obligation: lease.obligation, revision: committed },
-        client
-      ) : void 0
+      prepared || port || this.changeFeed ? async (client, committed) => {
+        if (prepared) await this.writePreparedRowSet(client, prepared, upload);
+        await this.appendChange(
+          client,
+          "revision",
+          lease.obligation.account.account_id,
+          revision.reporting_revision_id,
+          revision.reporting_obligation_id
+        );
+        await port?.recordLedgerChanged(
+          { obligation: lease.obligation, revision: withRows(committed, revision.rows) },
+          client
+        );
+      } : void 0
     );
+    return { inserted: result.inserted, value: withRows(result.value, revision.rows) };
   }
   async getRevision(id, accountId) {
-    return this.one(
+    const revision = await this.one(
       `SELECT revision.data FROM adcp_reporting_revisions revision
          JOIN adcp_reporting_obligations obligation ON obligation.obligation_id = revision.obligation_id
         WHERE revision.revision_id = $1 AND obligation.account_id = $2`,
       [id, accountId]
     );
+    return revision ? this.hydrateRevision(revision, accountId) : null;
   }
   async getRevisionMetadata(id, accountId) {
     return this.one(
@@ -691,12 +909,13 @@ ${managedDueArm}       )
       throw new RangeError("Reporting row page bounds are invalid");
     }
     const result = await this.query(
-      `SELECT jsonb_array_length(revision.data->'rows') AS total,
-              jsonb_path_query_array(
+      `SELECT revision.data ? 'rows' AS inline,
+              CASE WHEN revision.data ? 'rows' THEN jsonb_array_length(revision.data->'rows') END AS total,
+              CASE WHEN revision.data ? 'rows' THEN jsonb_path_query_array(
                 revision.data->'rows',
                 '$[$from to $to]',
                 jsonb_build_object('from', $3::bigint, 'to', $3::bigint + $4::bigint - 1)
-              ) AS rows
+              ) END AS rows
          FROM adcp_reporting_revisions revision
          JOIN adcp_reporting_obligations obligation ON obligation.obligation_id = revision.obligation_id
         WHERE revision.revision_id = $1 AND obligation.account_id = $2`,
@@ -704,15 +923,26 @@ ${managedDueArm}       )
     );
     const row = result.rows[0];
     if (!row) return null;
-    return { rows: clone(row.rows), total: Number(row.total) };
+    if (row.inline) return { rows: clone(row.rows ?? []), total: Number(row.total) };
+    const handle = await this.rowStorage.find(input.reporting_revision_id, input.account_id);
+    if (!handle) throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "revision rows are not recorded");
+    if (input.offset >= handle.rowCount) return { rows: [], total: handle.rowCount };
+    return {
+      rows: await this.rowStorage.readPage(handle, input.offset, input.limit, input.signal),
+      total: handle.rowCount
+    };
   }
   async listRevisions(obligationId) {
     const result = await this.query(
-      `SELECT data FROM adcp_reporting_revisions WHERE obligation_id = $1
-        ORDER BY revision_number, revision_id`,
+      `SELECT revision.data, obligation.account_id FROM adcp_reporting_revisions revision
+         JOIN adcp_reporting_obligations obligation ON obligation.obligation_id = revision.obligation_id
+        WHERE revision.obligation_id = $1
+        ORDER BY revision.revision_number, revision.revision_id`,
       [obligationId]
     );
-    return result.rows.map((row) => clone(row.data));
+    const revisions = [];
+    for (const row of result.rows) revisions.push(await this.hydrateRevision(clone(row.data), row.account_id));
+    return revisions;
   }
   async listRevisionMetadata(obligationId, accountId) {
     const result = await this.query(
@@ -727,7 +957,18 @@ ${managedDueArm}       )
   async commitAdjustment(adjustment, lease) {
     assertLeaseTarget(adjustment.reporting_obligation_id, lease);
     validateBoundRows(adjustment);
-    return this.putImmutable(
+    const prepared = this.rowStorageWrites ? await this.rowStorage.prepare({
+      rowSetId: adjustment.reporting_adjustment_id,
+      rowSetKind: "adjustment",
+      accountId: lease.obligation.account.account_id,
+      obligationId: adjustment.reporting_obligation_id,
+      rows: adjustment.rows,
+      periodStart: lease.obligation.period.start,
+      binding: adjustment.binding
+    }) : void 0;
+    const upload = prepared?.binding.kind === "object" ? await this.uploadRowSetUnlessCommitted(prepared, lease, "adcp_reporting_adjustments", "adjustment_id") : void 0;
+    const port = this.notificationActivityPort?.recordLedgerChanged ? this.notificationActivityPort : void 0;
+    const result = await this.putImmutable(
       `WITH leased_obligation AS (
          SELECT * FROM adcp_reporting_obligations obligation
           WHERE obligation.obligation_id = $2
@@ -758,7 +999,7 @@ ${managedDueArm}       )
         adjustment.adjusts_reporting_revision_id,
         adjustment.adjustmentNumber,
         adjustment.binding.sha256,
-        JSON.stringify(adjustment),
+        JSON.stringify(prepared ? withoutRows(adjustment) : adjustment),
         lease.owner,
         lease.generation
       ],
@@ -773,19 +1014,603 @@ ${managedDueArm}       )
         generation: lease.generation
       },
       adjustmentLegacyCanonicalDigestReplay,
-      this.notificationActivityPort?.recordLedgerChanged ? (client, committed) => this.notificationActivityPort.recordLedgerChanged(
-        { obligation: lease.obligation, adjustment: committed },
-        client
-      ) : void 0
+      prepared || port || this.changeFeed ? async (client, committed) => {
+        if (prepared) await this.writePreparedRowSet(client, prepared, upload);
+        await this.appendChange(
+          client,
+          "adjustment",
+          lease.obligation.account.account_id,
+          adjustment.reporting_adjustment_id,
+          adjustment.reporting_obligation_id
+        );
+        await port?.recordLedgerChanged(
+          { obligation: lease.obligation, adjustment: withRows(committed, adjustment.rows) },
+          client
+        );
+      } : void 0
     );
+    return { inserted: result.inserted, value: withRows(result.value, adjustment.rows) };
   }
   async listAdjustments(obligationId) {
     const result = await this.query(
-      `SELECT data FROM adcp_reporting_adjustments WHERE obligation_id = $1
-        ORDER BY adjustment_number, adjustment_id`,
+      `SELECT adjustment.data, obligation.account_id FROM adcp_reporting_adjustments adjustment
+         JOIN adcp_reporting_obligations obligation ON obligation.obligation_id = adjustment.obligation_id
+        WHERE adjustment.obligation_id = $1
+        ORDER BY adjustment.adjustment_number, adjustment.adjustment_id`,
       [obligationId]
     );
-    return result.rows.map((row) => clone(row.data));
+    const adjustments = [];
+    for (const row of result.rows) {
+      const adjustment = clone(row.data);
+      if (Array.isArray(adjustment.rows)) {
+        adjustments.push(adjustment);
+        continue;
+      }
+      const handle = await this.rowStorage.find(adjustment.reporting_adjustment_id, row.account_id);
+      if (!handle) throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "adjustment rows are not recorded");
+      adjustments.push({ ...adjustment, rows: await this.rowStorage.readAll(handle) });
+    }
+    return adjustments;
+  }
+  /**
+   * The obligation's current revision header: its official revision if one
+   * exists, otherwise its highest-numbered snapshot. An official revision is
+   * terminal, so this is always the highest revision number — one index
+   * lookup. Rows are read separately through `readRevisionRows`.
+   */
+  async getCurrentRevision(input) {
+    return this.one(
+      `SELECT revision.data - 'rows' AS data
+         FROM adcp_reporting_obligations obligation
+         JOIN LATERAL (
+           SELECT data FROM adcp_reporting_revisions current_revision
+            WHERE current_revision.obligation_id = obligation.obligation_id
+            ORDER BY current_revision.revision_number DESC LIMIT 1
+         ) revision ON TRUE
+        WHERE obligation.obligation_id = $1 AND obligation.account_id = $2`,
+      [input.reporting_obligation_id, input.account_id]
+    );
+  }
+  /**
+   * Current revision headers for an account's obligations whose period starts
+   * in `[period_start_from, period_start_to)`, ordered by period start.
+   * Obligations without a revision yet are omitted. Page with `cursor`.
+   */
+  async listCurrentRevisions(input) {
+    const limit = input.limit ?? 100;
+    positiveInteger(limit, "limit");
+    if (limit > 1e3) throw new RangeError("listCurrentRevisions limit must not exceed 1000");
+    let after;
+    if (input.cursor !== void 0) {
+      try {
+        const parsed = JSON.parse(Buffer.from(input.cursor, "base64url").toString("utf8"));
+        if (typeof parsed.start !== "string" || typeof parsed.id !== "string") throw new Error("invalid");
+        after = { start: parsed.start, id: parsed.id };
+      } catch {
+        throw new RangeError("listCurrentRevisions cursor is invalid");
+      }
+    }
+    const result = await this.query(
+      `SELECT revision.data - 'rows' AS data,
+              to_char(obligation.period_start AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"') AS start,
+              obligation.obligation_id AS id
+         FROM adcp_reporting_obligations obligation
+         JOIN LATERAL (
+           SELECT data FROM adcp_reporting_revisions current_revision
+            WHERE current_revision.obligation_id = obligation.obligation_id
+            ORDER BY current_revision.revision_number DESC LIMIT 1
+         ) revision ON TRUE
+        WHERE obligation.account_id = $1
+          AND obligation.period_start >= $2::timestamptz AND obligation.period_start < $3::timestamptz
+          AND ($4::text IS NULL OR obligation.data->>'delivery_config_id' = $4)
+          AND ($5::timestamptz IS NULL
+               OR (obligation.period_start, obligation.obligation_id) > ($5::timestamptz, $6::text))
+        ORDER BY obligation.period_start, obligation.obligation_id
+        LIMIT $7`,
+      [
+        input.account_id,
+        input.period_start_from,
+        input.period_start_to,
+        input.delivery_config_id ?? null,
+        after?.start ?? null,
+        after?.id ?? null,
+        limit + 1
+      ]
+    );
+    const page = result.rows.slice(0, limit);
+    const last = result.rows.length > limit ? page.at(-1) : void 0;
+    return {
+      revisions: page.map((row) => clone(row.data)),
+      ...last ? { cursor: Buffer.from(JSON.stringify({ start: last.start, id: last.id }), "utf8").toString("base64url") } : {}
+    };
+  }
+  /**
+   * 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
+   * than the retained history throws `ReportingChangeCursorExpiredError`;
+   * resynchronize from `listCurrentRevisions`.
+   */
+  async changesAfter(input = {}) {
+    if (!this.changeFeed) throw new Error("changesAfter requires the store changeFeed option");
+    const limit = input.limit ?? 500;
+    positiveInteger(limit, "limit");
+    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 ? {
+      seq: (await this.query(
+        `SELECT pruned_through_seq::text AS seq FROM adcp_reporting_change_account_horizon
+                    WHERE account_id = $1`,
+        [account]
+      )).rows[0]?.seq ?? "0"
+    } : (await this.query(
+      `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 position = cursor ?? {
+      v: 1,
+      account,
+      seq: horizon.seq,
+      ...account === null ? { xid: horizon.xid } : {}
+    };
+    const kinds = input.kinds?.length ? [...input.kinds] : null;
+    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
+              WHERE account_id = $1 AND seq > $2::bigint AND ($3::text[] IS NULL OR record_kind = ANY($3))
+              ORDER BY seq LIMIT $4`,
+      [account, position.seq, kinds, limit]
+    ) : await this.query(
+      `SELECT ${columns} FROM adcp_reporting_changes
+              WHERE (xid, seq) > ($1::text::xid8, $2::bigint)
+                AND xid < pg_snapshot_xmin(pg_current_snapshot())
+                AND ($3::text[] IS NULL OR record_kind = ANY($3))
+              ORDER BY xid, seq LIMIT $4`,
+      [position.xid ?? "0", position.seq, kinds, limit]
+    );
+    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 {
+      records: result.rows.map((row) => ({
+        kind: row.record_kind,
+        record_id: row.record_id,
+        reporting_obligation_id: row.obligation_id,
+        account_id: row.account_id,
+        recorded_at: row.recorded_at
+      })),
+      cursor: next
+    };
+  }
+  /**
+   * Record a named durable consumer's position. Registered consumers hold
+   * back change-table pruning until `maxFeedHoldDays` after their last update.
+   */
+  async saveFeedConsumerCursor(name, cursor) {
+    if (!this.changeFeed) throw new Error("saveFeedConsumerCursor requires the store changeFeed option");
+    let account;
+    try {
+      const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+      account = typeof parsed.account === "string" ? parsed.account : null;
+    } catch {
+      throw new RangeError("feed consumer cursor is invalid");
+    }
+    const decoded = decodeReportingChangeCursorV1(cursor, account);
+    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]
+    );
+  }
+  /**
+   * Delete change rows older than `changeRetentionDays` that every consumer
+   * updated within `maxFeedHoldDays` has passed, and advance the expiry
+   * horizon so older cursors fail closed.
+   */
+  async pruneChanges(input = {}) {
+    if (!this.changeFeed) return { deleted: 0 };
+    const retentionDays = input.changeRetentionDays ?? 30;
+    const holdDays = input.maxFeedHoldDays ?? 7;
+    positiveInteger(retentionDays, "changeRetentionDays");
+    positiveInteger(holdDays, "maxFeedHoldDays");
+    const limit = input.limit ?? 1e4;
+    positiveInteger(limit, "limit");
+    const deleted = await this.transaction(async (client) => {
+      const victims = await client.query(
+        `WITH victims AS (
+           SELECT change.seq FROM adcp_reporting_changes change
+            WHERE change.recorded_at < clock_timestamp() - ($1::integer * INTERVAL '1 day')
+              AND NOT EXISTS (
+                SELECT 1 FROM adcp_reporting_feed_consumers consumer
+                 WHERE consumer.updated_at > clock_timestamp() - ($2::integer * INTERVAL '1 day')
+                   AND ((consumer.account_id IS NULL
+                         AND (change.xid, change.seq) > (consumer.cursor_xid, consumer.cursor_seq))
+                     OR (consumer.account_id = change.account_id AND change.seq > consumer.cursor_seq))
+              )
+            ORDER BY change.seq LIMIT $3
+         )
+         DELETE FROM adcp_reporting_changes change USING victims
+          WHERE change.seq = victims.seq
+         RETURNING change.seq::text AS seq, change.xid::text AS xid, change.account_id`,
+        [retentionDays, holdDays, limit]
+      );
+      if (victims.rows.length === 0) return 0;
+      const highest = victims.rows.reduce(
+        (max, row) => BigInt(row.xid) > BigInt(max.xid) || row.xid === max.xid && BigInt(row.seq) > BigInt(max.seq) ? row : max
+      );
+      await client.query(
+        `UPDATE adcp_reporting_change_horizon
+            SET (pruned_through_xid, pruned_through_seq) = ($1::text::xid8, $2::bigint)
+          WHERE singleton AND ($1::text::xid8, $2::bigint) > (pruned_through_xid, pruned_through_seq)`,
+        [highest.xid, highest.seq]
+      );
+      const perAccount = /* @__PURE__ */ new Map();
+      for (const row of victims.rows) {
+        const seq = BigInt(row.seq);
+        if (seq > (perAccount.get(row.account_id) ?? 0n)) perAccount.set(row.account_id, seq);
+      }
+      for (const [accountId, seq] of perAccount) {
+        await client.query(
+          `INSERT INTO adcp_reporting_change_account_horizon (account_id, pruned_through_seq) VALUES ($1, $2::bigint)
+           ON CONFLICT (account_id) DO UPDATE
+              SET pruned_through_seq = GREATEST(adcp_reporting_change_account_horizon.pruned_through_seq,
+                                                EXCLUDED.pruned_through_seq)`,
+          [accountId, seq.toString()]
+        );
+      }
+      return victims.rows.length;
+    });
+    return { deleted };
+  }
+  /**
+   * Retire whole reporting periods whose retention has elapsed (shared SDK
+   * persistence spec §4). A period is eligible once both its end and its
+   * latest publication are older than `max(statusRetentionDays,
+   * recordRetentionDays)`, no worker holds its lease, and no Managed Delivery
+   * materialization still references it. Retirement is period-aligned and
+   * resumable:
+   *
+   * 1. under the account lock, record a `retiring` tombstone and mark the
+   *    period's row sets `pruning`, so exact reads answer as expired;
+   * 2. delete the period's external row objects at their recorded versions;
+   * 3. under the account lock, delete the period's ledger records (rows,
+   *    revisions, adjustments, consumer statuses, issues, transitions,
+   *    lifecycle state, obligation) and mark the tombstone `retired`.
+   *
+   * Planners skip retired periods, and `ledger_retained_from` advances past
+   * them because their obligations no longer exist.
+   */
+  async retireExpiredPeriods(input) {
+    if (!Number.isSafeInteger(input.statusRetentionDays) || input.statusRetentionDays < 1) {
+      throw new RangeError("statusRetentionDays must be a positive integer");
+    }
+    const recordDays = input.recordRetentionDays ?? input.statusRetentionDays;
+    if (!Number.isSafeInteger(recordDays) || recordDays < input.statusRetentionDays) {
+      throw new RangeError("recordRetentionDays must be an integer no shorter than statusRetentionDays");
+    }
+    const limit = input.limit ?? 100;
+    positiveInteger(limit, "limit");
+    const tables = await this.optionalTables();
+    const materializationHold = tables.has("adcp_reporting_materializations") ? `AND NOT EXISTS (SELECT 1 FROM adcp_reporting_materializations hold WHERE hold.obligation_id = obligation.obligation_id)` : "";
+    const candidates = await this.query(
+      `SELECT obligation_id, account_id FROM (
+         SELECT tombstone.obligation_id, tombstone.account_id, 0 AS resume, tombstone.period_end
+           FROM adcp_reporting_obligation_tombstones tombstone
+          WHERE tombstone.state = 'retiring' AND ($2::text IS NULL OR tombstone.account_id = $2)
+         UNION ALL
+         SELECT obligation.obligation_id, obligation.account_id, 1, obligation.period_end
+           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()
+            AND (obligation.lease_expires_at IS NULL OR obligation.lease_expires_at <= clock_timestamp())
+            AND COALESCE((SELECT MAX(revision.recorded_at) FROM adcp_reporting_revisions revision
+                           WHERE revision.obligation_id = obligation.obligation_id), obligation.created_at)
+                + ($3::integer * INTERVAL '1 day') <= clock_timestamp()
+            AND COALESCE((SELECT MAX(adjustment.recorded_at) FROM adcp_reporting_adjustments adjustment
+                           WHERE adjustment.obligation_id = obligation.obligation_id), '-infinity'::timestamptz)
+                + ($3::integer * INTERVAL '1 day') <= clock_timestamp()
+            AND NOT EXISTS (SELECT 1 FROM adcp_reporting_obligation_tombstones tombstone
+                             WHERE tombstone.obligation_id = obligation.obligation_id)
+            ${materializationHold}
+       ) candidate
+       ORDER BY resume, period_end, obligation_id
+       LIMIT $1`,
+      [limit, input.account_id ?? null, recordDays]
+    );
+    let retired = 0;
+    const failed = [];
+    const failures = [];
+    for (const candidate of candidates.rows) {
+      input.signal?.throwIfAborted();
+      try {
+        await this.retirePeriod(candidate.obligation_id, candidate.account_id, tables, input.signal);
+        retired += 1;
+      } catch (error) {
+        if (error instanceof ReportingLedgerPeriodRetiredError) continue;
+        failed.push(candidate.obligation_id);
+        failures.push({
+          reporting_obligation_id: candidate.obligation_id,
+          cause: isReportingRowStoreError(error) ? error.code : error instanceof Error ? error.name : "Error"
+        });
+      }
+    }
+    return { retired, failed, failures };
+  }
+  async retirePeriod(obligationId, accountId, tables, signal) {
+    const rowStorage = tables.has("adcp_reporting_row_sets");
+    await this.transaction(
+      async (client) => {
+        await client.query(
+          `INSERT INTO adcp_reporting_obligation_tombstones
+             (obligation_id, account_id, configuration_id, period_ordinal, period_start, period_end, state,
+              final_revision_id, final_content_sha256, revision_count, adjustment_count)
+           SELECT obligation.obligation_id, obligation.account_id, obligation.configuration_id,
+                  obligation.period_ordinal, obligation.period_start, obligation.period_end, 'retiring',
+                  latest.revision_id, latest.content_sha256,
+                  (SELECT count(*) FROM adcp_reporting_revisions revision WHERE revision.obligation_id = obligation.obligation_id),
+                  (SELECT count(*) FROM adcp_reporting_adjustments adjustment WHERE adjustment.obligation_id = obligation.obligation_id)
+             FROM adcp_reporting_obligations obligation
+             LEFT JOIN LATERAL (
+               SELECT revision.revision_id, revision.content_sha256 FROM adcp_reporting_revisions revision
+                WHERE revision.obligation_id = obligation.obligation_id
+                ORDER BY revision.revision_number DESC LIMIT 1
+             ) latest ON TRUE
+            WHERE obligation.obligation_id = $1
+           ON CONFLICT (obligation_id) DO NOTHING`,
+          [obligationId]
+        );
+        if (rowStorage) {
+          await client.query(
+            `UPDATE adcp_reporting_row_sets SET rows_state = 'pruning', rows_state_changed_at = clock_timestamp()
+              WHERE obligation_id = $1 AND rows_state IN ('live', 'unavailable')`,
+            [obligationId]
+          );
+        }
+      },
+      { preBeginAdvisoryLock: accountLock(accountId) }
+    );
+    if (rowStorage) {
+      const objects = await this.query(
+        `SELECT DISTINCT row_set.row_binding_id, chunk.object_key, chunk.native_version
+           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`,
+        [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 });
+        byBinding.set(row.row_binding_id, list);
+      }
+      for (const [bindingId, list] of byBinding) await this.rowStorage.deleteObjects(bindingId, list, signal);
+    }
+    await this.transaction(
+      async (client) => {
+        const revisionIds = `SELECT revision_id FROM adcp_reporting_revisions WHERE obligation_id = $1`;
+        if (rowStorage) {
+          await client.query(`DELETE FROM adcp_reporting_row_chunks WHERE obligation_id = $1`, [obligationId]);
+          await client.query(`DELETE FROM adcp_reporting_row_sets WHERE obligation_id = $1`, [obligationId]);
+          await client.query(`DELETE FROM adcp_reporting_chunk_bodies WHERE account_id = $2 AND obligation_id = $1`, [
+            obligationId,
+            accountId
+          ]);
+        }
+        await client.query(
+          `DELETE FROM adcp_reporting_consumer_statuses
+            WHERE obligation_id = $1 OR revision_id IN (${revisionIds})`,
+          [obligationId]
+        );
+        await client.query(`DELETE FROM adcp_reporting_adjustments WHERE obligation_id = $1`, [obligationId]);
+        await client.query(`DELETE FROM adcp_reporting_revisions WHERE obligation_id = $1`, [obligationId]);
+        await client.query(`DELETE FROM adcp_reporting_issues WHERE obligation_id = $1`, [obligationId]);
+        await client.query(`DELETE FROM adcp_reporting_transitions WHERE obligation_id = $1`, [obligationId]);
+        await client.query(`DELETE FROM adcp_reporting_lifecycle_state WHERE obligation_id = $1`, [obligationId]);
+        await client.query(`DELETE FROM adcp_reporting_obligations WHERE obligation_id = $1`, [obligationId]);
+        const retiredNow = await client.query(
+          `UPDATE adcp_reporting_obligation_tombstones SET state = 'retired', retired_at = clock_timestamp()
+            WHERE obligation_id = $1 AND state = 'retiring'`,
+          [obligationId]
+        );
+        if (retiredNow.rowCount === 1) {
+          await this.appendChange(client, "retirement", accountId, obligationId, obligationId);
+        }
+      },
+      { preBeginAdvisoryLock: accountLock(accountId) }
+    );
+  }
+  /**
+   * Resolve abandoned object uploads (spec §4.3). An expired `open` write
+   * intent whose ledger commit never happened is moved to `sweeping` under
+   * the account lock, so no writer can commit against it, then only the
+   * objects that upload created — never adopted ones, never any object a
+   * committed chunk references — are deleted at their recorded versions.
+   * Interrupted sweeps resume.
+   */
+  async sweepRowWriteIntents(input = {}) {
+    const limit = input.limit ?? 100;
+    positiveInteger(limit, "limit");
+    const tables = await this.optionalTables();
+    if (!tables.has("adcp_reporting_row_write_intents")) return { swept: 0, objectsDeleted: 0, failed: 0 };
+    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]
+    );
+    let swept = 0;
+    let objectsDeleted = 0;
+    let failed = 0;
+    for (const intent of expired.rows) {
+      input.signal?.throwIfAborted();
+      const key = [intent.row_binding_id, intent.row_set_id, intent.content_sha256];
+      try {
+        const claimed = await this.transaction(
+          async (client) => {
+            const updated = await client.query(
+              `UPDATE adcp_reporting_row_write_intents SET state = 'sweeping'
+                WHERE row_binding_id = $1 AND row_set_id = $2 AND content_sha256 = $3
+                  AND (state = 'sweeping' OR expires_at <= clock_timestamp())
+                RETURNING created_objects`,
+              key
+            );
+            return updated.rows[0]?.created_objects;
+          },
+          { preBeginAdvisoryLock: accountLock(intent.account_id) }
+        );
+        if (!claimed) continue;
+        const orphaned = [];
+        for (const object of claimed) {
+          const referenced = await this.query(
+            `SELECT 1 FROM adcp_reporting_row_chunks WHERE object_key = $1 AND native_version = $2 LIMIT 1`,
+            [object.objectKey, object.nativeVersion]
+          );
+          if (referenced.rows.length === 0) orphaned.push(object);
+        }
+        if (orphaned.length > 0) await this.rowStorage.deleteObjects(intent.row_binding_id, orphaned, input.signal);
+        await this.query(
+          `DELETE FROM adcp_reporting_row_write_intents
+            WHERE row_binding_id = $1 AND row_set_id = $2 AND content_sha256 = $3 AND state = 'sweeping'`,
+          key
+        );
+        swept += 1;
+        objectsDeleted += orphaned.length;
+      } catch {
+        failed += 1;
+      }
+    }
+    return { swept, objectsDeleted, failed };
+  }
+  async optionalTables() {
+    const result = await this.query(
+      `SELECT table_name AS name FROM information_schema.tables
+        WHERE table_schema = current_schema()
+          AND table_name IN ('adcp_reporting_row_sets', 'adcp_reporting_row_write_intents',
+                             'adcp_reporting_materializations')`
+    );
+    return new Set(result.rows.map((row) => row.name));
+  }
+  /**
+   * Upload an object-kind row set before its ledger commit (spec §3.5):
+   * skip when the document already exists (replay), refuse unless the lease
+   * still covers the upload deadline, open or take over an expired write
+   * intent under the account lock, then write every chunk create-only,
+   * recording each object this upload created in the intent first.
+   */
+  async uploadRowSetUnlessCommitted(prepared, lease, table, idColumn) {
+    const { input } = prepared;
+    const committed = await this.query(`SELECT 1 FROM ${table} WHERE ${idColumn} = $1`, [input.rowSetId]);
+    if (committed.rows.length > 0) return void 0;
+    const shared = await this.rowStorage.findShareable(this.pool, prepared);
+    if (shared) return { locators: shared.locators, sharedFrom: shared.rowSetId };
+    const ownerToken = reportingRowWriteIntentIdV1();
+    const budget = this.rowStorage.writeDeadlineMilliseconds;
+    const intentKey = [prepared.bindingId, input.rowSetId, input.binding.sha256];
+    await this.transaction(
+      async (client) => {
+        const opened = await client.query(
+          `INSERT INTO adcp_reporting_row_write_intents
+             (row_binding_id, account_id, row_set_id, content_sha256, state, owner_token, expires_at)
+           SELECT $1, $2, $3, $4, 'open', $5, obligation.lease_expires_at + ($6::bigint * INTERVAL '1 millisecond')
+             FROM adcp_reporting_obligations obligation
+            WHERE obligation.obligation_id = $7 AND obligation.lease_owner = $8
+              AND obligation.lease_generation = $9
+              AND obligation.lease_expires_at - clock_timestamp() >= (($6::bigint + 5000) * INTERVAL '1 millisecond')
+           ON CONFLICT (row_binding_id, row_set_id, content_sha256) DO UPDATE
+              SET owner_token = EXCLUDED.owner_token, expires_at = EXCLUDED.expires_at
+            WHERE adcp_reporting_row_write_intents.state = 'open'
+              AND adcp_reporting_row_write_intents.expires_at <= clock_timestamp()
+           RETURNING owner_token`,
+          [
+            prepared.bindingId,
+            input.accountId,
+            input.rowSetId,
+            input.binding.sha256,
+            ownerToken,
+            budget,
+            input.obligationId,
+            lease.owner,
+            lease.generation
+          ]
+        );
+        if (opened.rows.length === 1) return;
+        const held = await client.query(
+          `SELECT lease_expires_at - clock_timestamp() >= (($4::bigint + 5000) * INTERVAL '1 millisecond') AS budget
+             FROM adcp_reporting_obligations
+            WHERE obligation_id = $1 AND lease_owner = $2 AND lease_generation = $3
+              AND lease_expires_at > clock_timestamp()`,
+          [input.obligationId, lease.owner, lease.generation, budget]
+        );
+        if (held.rows.length === 0) throw new ReportingLedgerLeaseLostError();
+        if (!held.rows[0].budget) {
+          throw new ReportingRowStoreError("DEADLINE_EXCEEDED", "the lease does not cover the row upload deadline");
+        }
+        throw new ReportingRowStoreError("STATE_UNAVAILABLE", "another writer holds this row upload");
+      },
+      { preBeginAdvisoryLock: accountLock(input.accountId) }
+    );
+    const locators = await this.rowStorage.upload(prepared, ownerToken, async (object) => {
+      const recorded = await this.query(
+        `UPDATE adcp_reporting_row_write_intents
+            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])]
+      );
+      if (recorded.rowCount !== 1) {
+        throw new ReportingRowStoreError("STATE_UNAVAILABLE", "the row upload intent was taken over or swept");
+      }
+    });
+    return { locators, ownerToken };
+  }
+  /** Persist a prepared row set and close its upload intent in the ledger commit transaction. */
+  async writePreparedRowSet(client, prepared, upload) {
+    if (prepared.binding.kind === "postgres") {
+      const shared = await this.rowStorage.findShareable(client, prepared);
+      await this.rowStorage.writeInTransaction(client, prepared, void 0, shared?.rowSetId);
+      return;
+    }
+    if (!upload) throw new ReportingRowStoreError("STATE_UNAVAILABLE", "object rows were not uploaded");
+    if (upload.sharedFrom) {
+      const live = await client.query(
+        `SELECT 1 FROM adcp_reporting_row_sets WHERE row_set_id = $1 AND rows_state = 'live' FOR SHARE`,
+        [upload.sharedFrom]
+      );
+      if (live.rows.length !== 1) {
+        throw new ReportingRowStoreError("STATE_UNAVAILABLE", "the shared row set is no longer live");
+      }
+    } else {
+      const closed = await client.query(
+        `DELETE FROM adcp_reporting_row_write_intents
+          WHERE row_binding_id = $1 AND row_set_id = $2 AND content_sha256 = $3
+            AND owner_token = $4 AND state = 'open'`,
+        [prepared.bindingId, prepared.input.rowSetId, prepared.input.binding.sha256, upload.ownerToken]
+      );
+      if (closed.rowCount !== 1) {
+        throw new ReportingRowStoreError("STATE_UNAVAILABLE", "the row upload intent was taken over or swept");
+      }
+    }
+    await this.rowStorage.writeInTransaction(client, prepared, upload.locators, upload.sharedFrom);
+  }
+  /** Attach verified rows to a revision document whose rows live in row storage. */
+  async hydrateRevision(revision, accountId) {
+    if (Array.isArray(revision.rows)) return revision;
+    const handle = await this.rowStorage.find(revision.reporting_revision_id, accountId);
+    if (!handle) throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "revision rows are not recorded");
+    if (handle.contentSha256 !== revision.binding.sha256 || handle.rowCount !== revision.binding.rowCount) {
+      throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "row set does not match the revision binding");
+    }
+    return { ...revision, rows: await this.rowStorage.readAll(handle, revision.wireRevision.control_totals) };
   }
   async listAdjustmentMetadata(obligationId) {
     const result = await this.query(
@@ -2641,7 +3466,7 @@ ${managedDueArm}       )
           releaseError = rollbackCause instanceof Error ? rollbackCause : new Error("Reporting ledger rollback failed");
         }
       }
-      if (error instanceof ReportingLedgerLeaseLostError || error instanceof ReportingLedgerContinuityError || error instanceof ReportingLedgerSnapshotUnavailableError || error instanceof ReportingConsumerStatusConflictError) {
+      if (error instanceof ReportingLedgerLeaseLostError || error instanceof ReportingLedgerContinuityError || error instanceof ReportingLedgerPeriodRetiredError || error instanceof ReportingLedgerSnapshotUnavailableError || error instanceof ReportingConsumerStatusConflictError || isReportingRowStoreError(error)) {
         throw error;
       }
       throw new Error("PostgresReportingLedgerStore transaction failed", { cause: error });
@@ -3092,6 +3917,13 @@ function clone(value) {
 function positiveInteger(value, name) {
   if (!Number.isSafeInteger(value) || value <= 0) throw new RangeError(`${name} must be a positive safe integer`);
 }
+function withoutRows(value) {
+  const { rows: _rows, ...rest } = value;
+  return rest;
+}
+function withRows(value, rows) {
+  return Array.isArray(value.rows) ? value : { ...value, rows: clone(rows) };
+}
 export {
   PostgresReportingLedgerStore,
   REPORTING_LEDGER_FINALITY_FENCE_CONSTRAINT,
@@ -3099,5 +3931,6 @@ export {
   REPORTING_LEDGER_MIGRATION,
   ReportingLedgerContinuityError,
   ReportingLedgerLeaseLostError,
+  ReportingLedgerPeriodRetiredError,
   sweepExpiredReportingLedgerState
 };