@adcp/sdk 15.4.0 → 15.5.0

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,127 @@ 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.
+     */
+    retireExpiredPeriods(input: {
+        statusRetentionDays: number;
+        recordRetentionDays?: 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;