@adcp/sdk 15.4.0 → 15.6.0

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

@@ -26,6 +26,7 @@ var import_node_crypto = require("node:crypto");
 var import_jcs = require('../../utils/jcs.js');
 var import_evidence = require('../evidence.js');
 var import_types = require('./types.js');
+var import_row_storage = require('./row-storage.js');
 var import_object_writes = require('./object-writes.js');
 var import_managed = require('./managed.js');
 const REPORTING_MANAGED_DELIVERY_MIGRATION = `
@@ -252,6 +253,7 @@ const MAX_RECEIPT_BATCH_RESULT_BYTES = 64 * 1024;
 class PostgresReportingManagedDeliveryStore {
   constructor(pool, options = {}) {
     this.pool = pool;
+    this.rowStorage = new import_row_storage.ReportingRowStorageV1(pool);
     if (options.statusRetentionDays !== void 0) positiveInteger(options.statusRetentionDays, "statusRetentionDays");
     if (options.evidenceRetentionDays !== void 0) {
       positiveInteger(options.evidenceRetentionDays, "evidenceRetentionDays");
@@ -466,6 +468,8 @@ class PostgresReportingManagedDeliveryStore {
       authorizationRevocationSeconds: policy.advertised_authorization_revocation_seconds
     };
   }
+  /** Read-only access to PostgreSQL row chunks for claim hydration. */
+  rowStorage;
   /** SQL fragment scoping a count to the active retention window, if one is set. */
   activeScope(column) {
     return this.evidenceRetentionDays === void 0 ? "" : ` AND ${column} >= clock_timestamp() - (${this.evidenceRetentionDays}::bigint * INTERVAL '1 day')`;
@@ -1171,7 +1175,7 @@ class PostgresReportingManagedDeliveryStore {
   }
   async claimMaterialization(input) {
     positiveInteger(input.lease_milliseconds, "lease_milliseconds");
-    return this.transaction(async (client) => {
+    const lease = await this.transaction(async (client) => {
       const selected = await client.query(
         `WITH candidate AS (
            SELECT materialization.materialization_id
@@ -1227,6 +1231,22 @@ class PostgresReportingManagedDeliveryStore {
         expires_at: row.expires_at.toISOString()
       };
     });
+    if (!lease || Array.isArray(lease.revision.rows)) return lease;
+    try {
+      const handle = await this.rowStorage.find(
+        lease.revision.reporting_revision_id,
+        lease.obligation.account.account_id
+      );
+      if (handle?.kind === "postgres") {
+        lease.revision = {
+          ...lease.revision,
+          rows: await this.rowStorage.readAll(handle, lease.revision.wireRevision.control_totals)
+        };
+      }
+    } catch (error) {
+      if (!(0, import_row_storage.isReportingRowStoreError)(error)) throw error;
+    }
+    return lease;
   }
   /**
    * Fails materializations that have used every delivery attempt.

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

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { canonicalize } from "../../utils/jcs.mjs";
 import { isReportingAdjustmentReceiptEvidence, isReportingReceiptEvidence } from "../evidence.mjs";
 import { REPORTING_LEDGER_AUTHORITY } from "./types.mjs";
+import { ReportingRowStorageV1, isReportingRowStoreError } from "./row-storage.mjs";
 import {
   assertReportingObjectWriteScope,
   reportingObjectWritePlanFingerprint,
@@ -237,6 +238,7 @@ const MAX_RECEIPT_BATCH_RESULT_BYTES = 64 * 1024;
 class PostgresReportingManagedDeliveryStore {
   constructor(pool, options = {}) {
     this.pool = pool;
+    this.rowStorage = new ReportingRowStorageV1(pool);
     if (options.statusRetentionDays !== void 0) positiveInteger(options.statusRetentionDays, "statusRetentionDays");
     if (options.evidenceRetentionDays !== void 0) {
       positiveInteger(options.evidenceRetentionDays, "evidenceRetentionDays");
@@ -451,6 +453,8 @@ class PostgresReportingManagedDeliveryStore {
       authorizationRevocationSeconds: policy.advertised_authorization_revocation_seconds
     };
   }
+  /** Read-only access to PostgreSQL row chunks for claim hydration. */
+  rowStorage;
   /** SQL fragment scoping a count to the active retention window, if one is set. */
   activeScope(column) {
     return this.evidenceRetentionDays === void 0 ? "" : ` AND ${column} >= clock_timestamp() - (${this.evidenceRetentionDays}::bigint * INTERVAL '1 day')`;
@@ -1156,7 +1160,7 @@ class PostgresReportingManagedDeliveryStore {
   }
   async claimMaterialization(input) {
     positiveInteger(input.lease_milliseconds, "lease_milliseconds");
-    return this.transaction(async (client) => {
+    const lease = await this.transaction(async (client) => {
       const selected = await client.query(
         `WITH candidate AS (
            SELECT materialization.materialization_id
@@ -1212,6 +1216,22 @@ class PostgresReportingManagedDeliveryStore {
         expires_at: row.expires_at.toISOString()
       };
     });
+    if (!lease || Array.isArray(lease.revision.rows)) return lease;
+    try {
+      const handle = await this.rowStorage.find(
+        lease.revision.reporting_revision_id,
+        lease.obligation.account.account_id
+      );
+      if (handle?.kind === "postgres") {
+        lease.revision = {
+          ...lease.revision,
+          rows: await this.rowStorage.readAll(handle, lease.revision.wireRevision.control_totals)
+        };
+      }
+    } catch (error) {
+      if (!isReportingRowStoreError(error)) throw error;
+    }
+    return lease;
   }
   /**
    * Fails materializations that have used every delivery attempt.

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

@@ -258,6 +258,15 @@ export interface ReportingManagedDeliveryWorkerOptionsV1 {
      */
     authorizationRevocationSeconds?: number;
     account_id?: string;
+    /**
+     * Loads verified rows for a claimed revision whose rows live in row storage
+     * rather than in the ledger document. `createReportingManagedDeliveryRuntime`
+     * supplies one backed by its Core store. PostgreSQL-kind chunks are
+     * hydrated by the managed store's claim itself; a direct caller whose rows
+     * live in an external binding must supply this, or the adapter receives a
+     * revision without rows.
+     */
+    hydrateRevision?: (revision: ReportingManagedDeliveryLeaseV1['revision'], account_id: string, signal: AbortSignal | undefined) => Promise<ReportingManagedDeliveryLeaseV1['revision']>;
 }
 export interface CreateReportingManagedDeliveryRuntimeOptionsV1<TContext extends {
     account?: unknown;

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

@@ -258,6 +258,15 @@ export interface ReportingManagedDeliveryWorkerOptionsV1 {
      */
     authorizationRevocationSeconds?: number;
     account_id?: string;
+    /**
+     * Loads verified rows for a claimed revision whose rows live in row storage
+     * rather than in the ledger document. `createReportingManagedDeliveryRuntime`
+     * supplies one backed by its Core store. PostgreSQL-kind chunks are
+     * hydrated by the managed store's claim itself; a direct caller whose rows
+     * live in an external binding must supply this, or the adapter receives a
+     * revision without rows.
+     */
+    hydrateRevision?: (revision: ReportingManagedDeliveryLeaseV1['revision'], account_id: string, signal: AbortSignal | undefined) => Promise<ReportingManagedDeliveryLeaseV1['revision']>;
 }
 export interface CreateReportingManagedDeliveryRuntimeOptionsV1<TContext extends {
     account?: unknown;

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

@@ -130,6 +130,13 @@ async function createReportingManagedDeliveryRuntime(options) {
     getMediaBuyDelivery,
     ...syncReportingReceipts ? { syncReportingReceipts } : {},
     runWorker: (workerOptions) => runManagedDeliveryWorker(options.store, options.adapter, {
+      ...typeof options.coreStore.getRevision === "function" ? {
+        hydrateRevision: async (revision, accountId) => {
+          const hydrated = await options.coreStore.getRevision(revision.reporting_revision_id, accountId);
+          if (!hydrated) throw new Error("Reporting revision is unavailable for delivery");
+          return hydrated;
+        }
+      } : {},
       ...workerOptions,
       minimumResourceRetentionDays: Math.max(
         options.resourceRetentionDays,
@@ -356,6 +363,17 @@ async function runManagedDeliveryWorker(store, adapter, options = {}) {
     if (!lease) break;
     counts.claimed += 1;
     try {
+      if (!Array.isArray(lease.revision.rows) && options.hydrateRevision) {
+        const hydrated = await options.hydrateRevision(
+          lease.revision,
+          lease.obligation.account.account_id,
+          options.signal
+        );
+        if (hydrated.reporting_revision_id !== lease.revision.reporting_revision_id || hydrated.binding.sha256 !== lease.revision.binding.sha256 || !Array.isArray(hydrated.rows)) {
+          throw new Error("Hydrated reporting revision does not match the claimed revision");
+        }
+        lease.revision = hydrated;
+      }
       const outcome = await withinDeadline(
         (signal) => adapter.deliver(
           {

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

@@ -103,6 +103,13 @@ async function createReportingManagedDeliveryRuntime(options) {
     getMediaBuyDelivery,
     ...syncReportingReceipts ? { syncReportingReceipts } : {},
     runWorker: (workerOptions) => runManagedDeliveryWorker(options.store, options.adapter, {
+      ...typeof options.coreStore.getRevision === "function" ? {
+        hydrateRevision: async (revision, accountId) => {
+          const hydrated = await options.coreStore.getRevision(revision.reporting_revision_id, accountId);
+          if (!hydrated) throw new Error("Reporting revision is unavailable for delivery");
+          return hydrated;
+        }
+      } : {},
       ...workerOptions,
       minimumResourceRetentionDays: Math.max(
         options.resourceRetentionDays,
@@ -329,6 +336,17 @@ async function runManagedDeliveryWorker(store, adapter, options = {}) {
     if (!lease) break;
     counts.claimed += 1;
     try {
+      if (!Array.isArray(lease.revision.rows) && options.hydrateRevision) {
+        const hydrated = await options.hydrateRevision(
+          lease.revision,
+          lease.obligation.account.account_id,
+          options.signal
+        );
+        if (hydrated.reporting_revision_id !== lease.revision.reporting_revision_id || hydrated.binding.sha256 !== lease.revision.binding.sha256 || !Array.isArray(hydrated.rows)) {
+          throw new Error("Hydrated reporting revision does not match the claimed revision");
+        }
+        lease.revision = hydrated;
+      }
       const outcome = await withinDeadline(
         (signal) => adapter.deliver(
           {

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

@@ -1,6 +1,8 @@
 import { REPORTING_LEDGER_AUTHORITY } from './types.mjs';
 import type { ReportingLedgerConfigurationV1, ReportingLedgerAdjustmentMetadataV1, ReportingLedgerAdjustmentV1, ReportingLedgerConsumerStatusV1, ReportingLedgerIssueV1, ReportingLedgerLeaseV1, ReportingLedgerObligationV1, ReportingLedgerPageV1, ReportingLedgerRevisionV1, ReportingLedgerSnapshotQueryV1, ReportingLedgerSnapshotV1, ReportingLedgerStatusTransitionV1, ReportingLedgerNotificationActivityPortV1, ReportingLedgerTransactionV1, ReportingObservedFinalityV1, ReportingLedgerStore, ReportingConsumerStatusBatchInputV1, ReportingConsumerStatusBatchResultV1, ReportingConsumerStatusReplayInputV1, ReportingLedgerRevisionMetadataV1, ReportingRevisionRowsPageV1, ReportingRevisionRowsReadV1, ReportingManagedLifecycleProjectionV1, ReportingLedgerAuthorityV1 } from './types.mjs';
 import type { ReportingConsumerMismatchEscalationV1 } from './types.mjs';
+import { type ReportingChangeKindV1, type ReportingChangesPageV1 } from './change-feed.mjs';
+import { type ReportingRowStorageOptionsV1 } from './row-storage.mjs';
 type QueryResultRow = Record<string, unknown>;
 interface ReportingPgResult<Row extends QueryResultRow> {
     rows: Row[];
@@ -86,10 +88,28 @@ export interface PostgresReportingLedgerStoreOptions {
      * lifecycle transaction. Its tables must be migrated before transitions run.
      */
     notificationActivityPort?: ReportingLedgerNotificationActivityPortV1<ReportingLedgerTransactionV1>;
+    /**
+     * Store new revision and adjustment rows as verified canonical JSONL chunks
+     * (see `REPORTING_ROW_STORAGE_MIGRATION`) instead of inline in the ledger
+     * document. `true` uses a single `postgres` binding. Revisions written
+     * before enabling this keep their inline rows; reads handle both forms
+     * whether or not this option is set.
+     */
+    rowStorage?: boolean | ReportingRowStorageOptionsV1;
+    /**
+     * Append obligation, revision, adjustment and retirement changes to the
+     * host change feed (`REPORTING_LEDGER_CHANGES_MIGRATION`, PostgreSQL 13+) in
+     * the same transaction as each record. Required for `changesAfter`.
+     */
+    changeFeed?: boolean;
 }
 export declare class ReportingLedgerLeaseLostError extends Error {
     constructor(message?: string);
 }
+/** A planner or writer named a period whose ledger records were retired by retention. */
+export declare class ReportingLedgerPeriodRetiredError extends Error {
+    constructor(message?: string);
+}
 export declare class ReportingLedgerContinuityError extends Error {
     constructor(message?: string);
 }
@@ -113,7 +133,36 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
     private readonly obligatedConsumers;
     readonly transactionalNotificationActivity: boolean;
     private readonly notificationActivityPort?;
+    private readonly rowStorage;
+    private readonly rowStorageWrites;
+    private readonly changeFeed;
     constructor(pool: ReportingPgPool, options?: PostgresReportingLedgerStoreOptions);
+    /** Append one host change-feed row inside the caller's account-locked transaction. */
+    private appendChange;
+    /** Probe and register row storage when enabled. Safe to call repeatedly. */
+    readyRowStorage(): Promise<void>;
+    /**
+     * 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.
+     */
+    migrateInlineRows(input?: {
+        limit?: number;
+        account_id?: string;
+        cursor?: string;
+        bindingId?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        migrated: number;
+        quarantined: string[];
+        cursor?: string;
+    }>;
     putConfiguration(configuration: ReportingLedgerConfigurationV1): Promise<{
         inserted: boolean;
         value: ReportingLedgerConfigurationV1;
@@ -124,6 +173,11 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
         value: ReportingLedgerObligationV1;
     }>;
     getObligation(id: string, account_id?: string): Promise<ReportingLedgerObligationV1 | null>;
+    /** Periods retired by retention; planners treat them as already covered. */
+    listRetiredObligationOrdinals(account_id?: string): Promise<{
+        configurationId: string;
+        periodOrdinal: number;
+    }[]>;
     listObligations(account_id?: string): Promise<ReportingLedgerObligationV1[]>;
     listLifecycleDueObligations(input: {
         ledgerAsOf: string;
@@ -152,6 +206,137 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
         value: ReportingLedgerAdjustmentV1;
     }>;
     listAdjustments(obligationId: string): Promise<ReportingLedgerAdjustmentV1[]>;
+    /**
+     * 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`.
+     */
+    getCurrentRevision(input: {
+        account_id: string;
+        reporting_obligation_id: string;
+    }): Promise<ReportingLedgerRevisionMetadataV1 | null>;
+    /**
+     * 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`.
+     */
+    listCurrentRevisions(input: {
+        account_id: string;
+        period_start_from: string;
+        period_start_to: string;
+        delivery_config_id?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        revisions: ReportingLedgerRevisionMetadataV1[];
+        cursor?: string;
+    }>;
+    /**
+     * 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`.
+     */
+    changesAfter(input?: {
+        cursor?: string;
+        account_id?: string;
+        kinds?: readonly ReportingChangeKindV1[];
+        limit?: number;
+    }): Promise<ReportingChangesPageV1>;
+    /**
+     * Record a named durable consumer's position. Registered consumers hold
+     * back change-table pruning until `maxFeedHoldDays` after their last update.
+     */
+    saveFeedConsumerCursor(name: string, cursor: string): Promise<void>;
+    /**
+     * Delete change rows older than `changeRetentionDays` that every consumer
+     * updated within `maxFeedHoldDays` has passed, and advance the expiry
+     * horizon so older cursors fail closed.
+     */
+    pruneChanges(input?: {
+        changeRetentionDays?: number;
+        maxFeedHoldDays?: number;
+        limit?: number;
+    }): Promise<{
+        deleted: number;
+    }>;
+    /**
+     * 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.
+     *
+     * When the change-feed tables exist, a period that is not yet retiring is
+     * also held while any live registered feed consumer (updated within
+     * `maxFeedHoldDays`, default 7) has not passed that period's change rows in
+     * the consumer's own feed order, the same rule `pruneChanges` applies. A
+     * held period is simply not a candidate this pass. A consumer that stays
+     * silent past `maxFeedHoldDays` stops holding, so retention is never
+     * blocked forever; it then falls behind retention and a sink sees the
+     * retired revisions as missing.
+     */
+    retireExpiredPeriods(input: {
+        statusRetentionDays: number;
+        recordRetentionDays?: number;
+        maxFeedHoldDays?: number;
+        limit?: number;
+        account_id?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        retired: number;
+        failed: string[];
+        /** Secret-free cause per failed period: a row-store code or the error class name. */
+        failures: {
+            reporting_obligation_id: string;
+            cause: string;
+        }[];
+    }>;
+    private retirePeriod;
+    /**
+     * 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.
+     */
+    sweepRowWriteIntents(input?: {
+        limit?: number;
+        account_id?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        swept: number;
+        objectsDeleted: number;
+        failed: number;
+    }>;
+    private optionalTables;
+    /**
+     * 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.
+     */
+    private uploadRowSetUnlessCommitted;
+    /** Persist a prepared row set and close its upload intent in the ledger commit transaction. */
+    private writePreparedRowSet;
+    /** Attach verified rows to a revision document whose rows live in row storage. */
+    private hydrateRevision;
     listAdjustmentMetadata(obligationId: string): Promise<ReportingLedgerAdjustmentMetadataV1[]>;
     putConsumerStatus(status: ReportingLedgerConsumerStatusV1): Promise<{
         inserted: boolean;

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

@@ -1,6 +1,8 @@
 import { REPORTING_LEDGER_AUTHORITY } from './types';
 import type { ReportingLedgerConfigurationV1, ReportingLedgerAdjustmentMetadataV1, ReportingLedgerAdjustmentV1, ReportingLedgerConsumerStatusV1, ReportingLedgerIssueV1, ReportingLedgerLeaseV1, ReportingLedgerObligationV1, ReportingLedgerPageV1, ReportingLedgerRevisionV1, ReportingLedgerSnapshotQueryV1, ReportingLedgerSnapshotV1, ReportingLedgerStatusTransitionV1, ReportingLedgerNotificationActivityPortV1, ReportingLedgerTransactionV1, ReportingObservedFinalityV1, ReportingLedgerStore, ReportingConsumerStatusBatchInputV1, ReportingConsumerStatusBatchResultV1, ReportingConsumerStatusReplayInputV1, ReportingLedgerRevisionMetadataV1, ReportingRevisionRowsPageV1, ReportingRevisionRowsReadV1, ReportingManagedLifecycleProjectionV1, ReportingLedgerAuthorityV1 } from './types';
 import type { ReportingConsumerMismatchEscalationV1 } from './types';
+import { type ReportingChangeKindV1, type ReportingChangesPageV1 } from './change-feed';
+import { type ReportingRowStorageOptionsV1 } from './row-storage';
 type QueryResultRow = Record<string, unknown>;
 interface ReportingPgResult<Row extends QueryResultRow> {
     rows: Row[];
@@ -86,10 +88,28 @@ export interface PostgresReportingLedgerStoreOptions {
      * lifecycle transaction. Its tables must be migrated before transitions run.
      */
     notificationActivityPort?: ReportingLedgerNotificationActivityPortV1<ReportingLedgerTransactionV1>;
+    /**
+     * Store new revision and adjustment rows as verified canonical JSONL chunks
+     * (see `REPORTING_ROW_STORAGE_MIGRATION`) instead of inline in the ledger
+     * document. `true` uses a single `postgres` binding. Revisions written
+     * before enabling this keep their inline rows; reads handle both forms
+     * whether or not this option is set.
+     */
+    rowStorage?: boolean | ReportingRowStorageOptionsV1;
+    /**
+     * Append obligation, revision, adjustment and retirement changes to the
+     * host change feed (`REPORTING_LEDGER_CHANGES_MIGRATION`, PostgreSQL 13+) in
+     * the same transaction as each record. Required for `changesAfter`.
+     */
+    changeFeed?: boolean;
 }
 export declare class ReportingLedgerLeaseLostError extends Error {
     constructor(message?: string);
 }
+/** A planner or writer named a period whose ledger records were retired by retention. */
+export declare class ReportingLedgerPeriodRetiredError extends Error {
+    constructor(message?: string);
+}
 export declare class ReportingLedgerContinuityError extends Error {
     constructor(message?: string);
 }
@@ -113,7 +133,36 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
     private readonly obligatedConsumers;
     readonly transactionalNotificationActivity: boolean;
     private readonly notificationActivityPort?;
+    private readonly rowStorage;
+    private readonly rowStorageWrites;
+    private readonly changeFeed;
     constructor(pool: ReportingPgPool, options?: PostgresReportingLedgerStoreOptions);
+    /** Append one host change-feed row inside the caller's account-locked transaction. */
+    private appendChange;
+    /** Probe and register row storage when enabled. Safe to call repeatedly. */
+    readyRowStorage(): Promise<void>;
+    /**
+     * 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.
+     */
+    migrateInlineRows(input?: {
+        limit?: number;
+        account_id?: string;
+        cursor?: string;
+        bindingId?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        migrated: number;
+        quarantined: string[];
+        cursor?: string;
+    }>;
     putConfiguration(configuration: ReportingLedgerConfigurationV1): Promise<{
         inserted: boolean;
         value: ReportingLedgerConfigurationV1;
@@ -124,6 +173,11 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
         value: ReportingLedgerObligationV1;
     }>;
     getObligation(id: string, account_id?: string): Promise<ReportingLedgerObligationV1 | null>;
+    /** Periods retired by retention; planners treat them as already covered. */
+    listRetiredObligationOrdinals(account_id?: string): Promise<{
+        configurationId: string;
+        periodOrdinal: number;
+    }[]>;
     listObligations(account_id?: string): Promise<ReportingLedgerObligationV1[]>;
     listLifecycleDueObligations(input: {
         ledgerAsOf: string;
@@ -152,6 +206,137 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
         value: ReportingLedgerAdjustmentV1;
     }>;
     listAdjustments(obligationId: string): Promise<ReportingLedgerAdjustmentV1[]>;
+    /**
+     * 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`.
+     */
+    getCurrentRevision(input: {
+        account_id: string;
+        reporting_obligation_id: string;
+    }): Promise<ReportingLedgerRevisionMetadataV1 | null>;
+    /**
+     * 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`.
+     */
+    listCurrentRevisions(input: {
+        account_id: string;
+        period_start_from: string;
+        period_start_to: string;
+        delivery_config_id?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        revisions: ReportingLedgerRevisionMetadataV1[];
+        cursor?: string;
+    }>;
+    /**
+     * 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`.
+     */
+    changesAfter(input?: {
+        cursor?: string;
+        account_id?: string;
+        kinds?: readonly ReportingChangeKindV1[];
+        limit?: number;
+    }): Promise<ReportingChangesPageV1>;
+    /**
+     * Record a named durable consumer's position. Registered consumers hold
+     * back change-table pruning until `maxFeedHoldDays` after their last update.
+     */
+    saveFeedConsumerCursor(name: string, cursor: string): Promise<void>;
+    /**
+     * Delete change rows older than `changeRetentionDays` that every consumer
+     * updated within `maxFeedHoldDays` has passed, and advance the expiry
+     * horizon so older cursors fail closed.
+     */
+    pruneChanges(input?: {
+        changeRetentionDays?: number;
+        maxFeedHoldDays?: number;
+        limit?: number;
+    }): Promise<{
+        deleted: number;
+    }>;
+    /**
+     * 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.
+     *
+     * When the change-feed tables exist, a period that is not yet retiring is
+     * also held while any live registered feed consumer (updated within
+     * `maxFeedHoldDays`, default 7) has not passed that period's change rows in
+     * the consumer's own feed order, the same rule `pruneChanges` applies. A
+     * held period is simply not a candidate this pass. A consumer that stays
+     * silent past `maxFeedHoldDays` stops holding, so retention is never
+     * blocked forever; it then falls behind retention and a sink sees the
+     * retired revisions as missing.
+     */
+    retireExpiredPeriods(input: {
+        statusRetentionDays: number;
+        recordRetentionDays?: number;
+        maxFeedHoldDays?: number;
+        limit?: number;
+        account_id?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        retired: number;
+        failed: string[];
+        /** Secret-free cause per failed period: a row-store code or the error class name. */
+        failures: {
+            reporting_obligation_id: string;
+            cause: string;
+        }[];
+    }>;
+    private retirePeriod;
+    /**
+     * 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.
+     */
+    sweepRowWriteIntents(input?: {
+        limit?: number;
+        account_id?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        swept: number;
+        objectsDeleted: number;
+        failed: number;
+    }>;
+    private optionalTables;
+    /**
+     * 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.
+     */
+    private uploadRowSetUnlessCommitted;
+    /** Persist a prepared row set and close its upload intent in the ledger commit transaction. */
+    private writePreparedRowSet;
+    /** Attach verified rows to a revision document whose rows live in row storage. */
+    private hydrateRevision;
     listAdjustmentMetadata(obligationId: string): Promise<ReportingLedgerAdjustmentMetadataV1[]>;
     putConsumerStatus(status: ReportingLedgerConsumerStatusV1): Promise<{
         inserted: boolean;