@adcp/sdk 15.2.2 → 15.4.0

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

@@ -3,6 +3,7 @@ import { canonicalJsonV1 } from "../source/index.mjs";
 import { moreSevereReportingHealthV1, projectManagedDelivery } from "./handler.mjs";
 import { compareReportingInstants } from "./instant.mjs";
 import { projectReportingObligationHealthV1 } from "./health.mjs";
+import { listAdjustmentMetadataFromStore, listRevisionMetadataFromStore } from "./revision-metadata.mjs";
 async function resolveLedgerAsOf(input, attempt) {
   const resolved = await input.store.readLedgerInstant?.() ?? (input.now ?? (() => /* @__PURE__ */ new Date()))().toISOString();
   if (input.ledgerAsOf === void 0) return resolved;
@@ -53,7 +54,7 @@ async function reconcileReportingStatusLifecycleV1(input, attempt = 0) {
   const transactionalNotifications = input.store.transactionalNotificationActivity === true;
   assertNotificationModesCompatible(input.store, input.subscribers);
   let ledgerAsOf = await resolveLedgerAsOf(input, attempt);
-  const revisions = await input.store.listRevisions(obligation.reporting_obligation_id);
+  const revisions = await listRevisionMetadataFromStore(input.store, obligation.reporting_obligation_id);
   let projected = revisions;
   const projectCore = (at) => projectReportingObligationHealthV1(
     obligation,
@@ -182,7 +183,7 @@ async function composeManagedLifecycleProjection(input, obligation, revisions, c
     ledgerAsOf: input.ledgerAsOf
   });
   if (!managed) return { projection: coreProjection };
-  const stored = await input.store.listAdjustments(obligation.reporting_obligation_id);
+  const stored = await listAdjustmentMetadataFromStore(input.store, obligation.reporting_obligation_id);
   const visibleAdjustmentIds = managed.visibleAdjustmentIds;
   const adjustments = visibleAdjustmentIds ? stored.filter((value) => visibleAdjustmentIds.includes(value.reporting_adjustment_id)) : stored.filter((value) => compareReportingInstants(value.createdAt, input.ledgerAsOf) <= 0);
   const rosterAuthoritative = managed.obligatedConsumerRosterComplete === true && managed.receiptEvidenceComplete !== false;

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

@@ -987,7 +987,7 @@ class PostgresReportingManagedDeliveryStore {
         ])
       );
       const candidates = await client.query(
-        `SELECT binding.data AS binding, obligation.data AS obligation, revision.data AS revision,
+        `SELECT binding.data AS binding, obligation.data AS obligation, revision.revision_id AS revision_id,
                 GREATEST(COALESCE(MAX(existing.attempt), 0), COALESCE(MAX(tomb.highest_attempt), 0))::integer + 1
                   AS attempt
            FROM adcp_reporting_managed_bindings binding
@@ -1007,7 +1007,7 @@ class PostgresReportingManagedDeliveryStore {
              ON tomb.configuration_id = binding.configuration_id AND tomb.revision_id = revision.revision_id
           WHERE ($1::text IS NULL OR binding.account_id = $1)
           GROUP BY binding.configuration_id, binding.data, obligation.obligation_id, obligation.data,
-                   revision.revision_id, revision.data
+                   revision.revision_id
          HAVING NOT COALESCE(BOOL_OR(existing.status IN ('pending','available','delivered')), false)
             AND NOT COALESCE(BOOL_OR(tomb.reached_success), false)
             AND GREATEST(COALESCE(MAX(existing.attempt), 0), COALESCE(MAX(tomb.highest_attempt), 0))
@@ -1022,11 +1022,11 @@ class PostgresReportingManagedDeliveryStore {
         const remaining = remainingByAccount.get(binding.account_id) ?? 0;
         if (remaining <= 0) continue;
         const obligation = candidate.obligation;
-        const revision = candidate.revision;
+        const revisionId = candidate.revision_id;
         const created_at = (/* @__PURE__ */ new Date()).toISOString();
         const materialization = {
           reporting_materialization_id: `rmat_${(0, import_node_crypto.randomUUID)()}`,
-          reporting_revision_id: revision.reporting_revision_id,
+          reporting_revision_id: revisionId,
           reporting_obligation_id: obligation.reporting_obligation_id,
           delivery_config_id: binding.delivery_config_id,
           delivery_config_version: binding.delivery_config_version,
@@ -1049,7 +1049,7 @@ class PostgresReportingManagedDeliveryStore {
             binding.account_id,
             binding.configurationId,
             obligation.reporting_obligation_id,
-            revision.reporting_revision_id,
+            revisionId,
             binding.destination_ref,
             binding.authorization_generation,
             candidate.attempt,

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

@@ -972,7 +972,7 @@ class PostgresReportingManagedDeliveryStore {
         ])
       );
       const candidates = await client.query(
-        `SELECT binding.data AS binding, obligation.data AS obligation, revision.data AS revision,
+        `SELECT binding.data AS binding, obligation.data AS obligation, revision.revision_id AS revision_id,
                 GREATEST(COALESCE(MAX(existing.attempt), 0), COALESCE(MAX(tomb.highest_attempt), 0))::integer + 1
                   AS attempt
            FROM adcp_reporting_managed_bindings binding
@@ -992,7 +992,7 @@ class PostgresReportingManagedDeliveryStore {
              ON tomb.configuration_id = binding.configuration_id AND tomb.revision_id = revision.revision_id
           WHERE ($1::text IS NULL OR binding.account_id = $1)
           GROUP BY binding.configuration_id, binding.data, obligation.obligation_id, obligation.data,
-                   revision.revision_id, revision.data
+                   revision.revision_id
          HAVING NOT COALESCE(BOOL_OR(existing.status IN ('pending','available','delivered')), false)
             AND NOT COALESCE(BOOL_OR(tomb.reached_success), false)
             AND GREATEST(COALESCE(MAX(existing.attempt), 0), COALESCE(MAX(tomb.highest_attempt), 0))
@@ -1007,11 +1007,11 @@ class PostgresReportingManagedDeliveryStore {
         const remaining = remainingByAccount.get(binding.account_id) ?? 0;
         if (remaining <= 0) continue;
         const obligation = candidate.obligation;
-        const revision = candidate.revision;
+        const revisionId = candidate.revision_id;
         const created_at = (/* @__PURE__ */ new Date()).toISOString();
         const materialization = {
           reporting_materialization_id: `rmat_${randomUUID()}`,
-          reporting_revision_id: revision.reporting_revision_id,
+          reporting_revision_id: revisionId,
           reporting_obligation_id: obligation.reporting_obligation_id,
           delivery_config_id: binding.delivery_config_id,
           delivery_config_version: binding.delivery_config_version,
@@ -1034,7 +1034,7 @@ class PostgresReportingManagedDeliveryStore {
             binding.account_id,
             binding.configurationId,
             obligation.reporting_obligation_id,
-            revision.reporting_revision_id,
+            revisionId,
             binding.destination_ref,
             binding.authorization_generation,
             candidate.attempt,

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

@@ -1,5 +1,5 @@
 import { REPORTING_LEDGER_AUTHORITY } from './types.mjs';
-import type { ReportingLedgerConfigurationV1, ReportingLedgerAdjustmentV1, ReportingLedgerConsumerStatusV1, ReportingLedgerIssueV1, ReportingLedgerLeaseV1, ReportingLedgerObligationV1, ReportingLedgerPageV1, ReportingLedgerRevisionV1, ReportingLedgerSnapshotQueryV1, ReportingLedgerSnapshotV1, ReportingLedgerStatusTransitionV1, ReportingLedgerNotificationActivityPortV1, ReportingLedgerTransactionV1, ReportingObservedFinalityV1, ReportingLedgerStore, ReportingConsumerStatusBatchInputV1, ReportingConsumerStatusBatchResultV1, ReportingConsumerStatusReplayInputV1, ReportingLedgerRevisionMetadataV1, ReportingManagedLifecycleProjectionV1, ReportingLedgerAuthorityV1 } 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';
 type QueryResultRow = Record<string, unknown>;
 interface ReportingPgResult<Row extends QueryResultRow> {
@@ -144,12 +144,15 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
     }>;
     getRevision(id: string, accountId: string): Promise<ReportingLedgerRevisionV1 | null>;
     getRevisionMetadata(id: string, accountId: string): Promise<ReportingLedgerRevisionMetadataV1 | null>;
+    readRevisionRows(input: ReportingRevisionRowsReadV1): Promise<ReportingRevisionRowsPageV1 | null>;
     listRevisions(obligationId: string): Promise<ReportingLedgerRevisionV1[]>;
+    listRevisionMetadata(obligationId: string, accountId?: string): Promise<ReportingLedgerRevisionMetadataV1[]>;
     commitAdjustment(adjustment: ReportingLedgerAdjustmentV1, lease: ReportingLedgerLeaseV1): Promise<{
         inserted: boolean;
         value: ReportingLedgerAdjustmentV1;
     }>;
     listAdjustments(obligationId: string): Promise<ReportingLedgerAdjustmentV1[]>;
+    listAdjustmentMetadata(obligationId: string): Promise<ReportingLedgerAdjustmentMetadataV1[]>;
     putConsumerStatus(status: ReportingLedgerConsumerStatusV1): Promise<{
         inserted: boolean;
         value: ReportingLedgerConsumerStatusV1;

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

@@ -1,5 +1,5 @@
 import { REPORTING_LEDGER_AUTHORITY } from './types';
-import type { ReportingLedgerConfigurationV1, ReportingLedgerAdjustmentV1, ReportingLedgerConsumerStatusV1, ReportingLedgerIssueV1, ReportingLedgerLeaseV1, ReportingLedgerObligationV1, ReportingLedgerPageV1, ReportingLedgerRevisionV1, ReportingLedgerSnapshotQueryV1, ReportingLedgerSnapshotV1, ReportingLedgerStatusTransitionV1, ReportingLedgerNotificationActivityPortV1, ReportingLedgerTransactionV1, ReportingObservedFinalityV1, ReportingLedgerStore, ReportingConsumerStatusBatchInputV1, ReportingConsumerStatusBatchResultV1, ReportingConsumerStatusReplayInputV1, ReportingLedgerRevisionMetadataV1, ReportingManagedLifecycleProjectionV1, ReportingLedgerAuthorityV1 } 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';
 type QueryResultRow = Record<string, unknown>;
 interface ReportingPgResult<Row extends QueryResultRow> {
@@ -144,12 +144,15 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
     }>;
     getRevision(id: string, accountId: string): Promise<ReportingLedgerRevisionV1 | null>;
     getRevisionMetadata(id: string, accountId: string): Promise<ReportingLedgerRevisionMetadataV1 | null>;
+    readRevisionRows(input: ReportingRevisionRowsReadV1): Promise<ReportingRevisionRowsPageV1 | null>;
     listRevisions(obligationId: string): Promise<ReportingLedgerRevisionV1[]>;
+    listRevisionMetadata(obligationId: string, accountId?: string): Promise<ReportingLedgerRevisionMetadataV1[]>;
     commitAdjustment(adjustment: ReportingLedgerAdjustmentV1, lease: ReportingLedgerLeaseV1): Promise<{
         inserted: boolean;
         value: ReportingLedgerAdjustmentV1;
     }>;
     listAdjustments(obligationId: string): Promise<ReportingLedgerAdjustmentV1[]>;
+    listAdjustmentMetadata(obligationId: string): Promise<ReportingLedgerAdjustmentMetadataV1[]>;
     putConsumerStatus(status: ReportingLedgerConsumerStatusV1): Promise<{
         inserted: boolean;
         value: ReportingLedgerConsumerStatusV1;

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

@@ -695,6 +695,26 @@ ${managedDueArm}       )
       [id, accountId]
     );
   }
+  async readRevisionRows(input) {
+    if (!Number.isSafeInteger(input.offset) || input.offset < 0 || !Number.isSafeInteger(input.limit) || input.limit < 1) {
+      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(
+                revision.data->'rows',
+                '$[$from to $to]',
+                jsonb_build_object('from', $3::bigint, 'to', $3::bigint + $4::bigint - 1)
+              ) 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`,
+      [input.reporting_revision_id, input.account_id, input.offset, input.limit]
+    );
+    const row = result.rows[0];
+    if (!row) return null;
+    return { rows: clone(row.rows), total: Number(row.total) };
+  }
   async listRevisions(obligationId) {
     const result = await this.query(
       `SELECT data FROM adcp_reporting_revisions WHERE obligation_id = $1
@@ -703,6 +723,16 @@ ${managedDueArm}       )
     );
     return result.rows.map((row) => clone(row.data));
   }
+  async listRevisionMetadata(obligationId, accountId) {
+    const result = await this.query(
+      `SELECT revision.data - 'rows' AS data FROM adcp_reporting_revisions revision
+         JOIN adcp_reporting_obligations obligation ON obligation.obligation_id = revision.obligation_id
+        WHERE revision.obligation_id = $1 AND ($2::text IS NULL OR obligation.account_id = $2)
+        ORDER BY revision.revision_number, revision.revision_id`,
+      [obligationId, accountId ?? null]
+    );
+    return result.rows.map((row) => clone(row.data));
+  }
   async commitAdjustment(adjustment, lease) {
     assertLeaseTarget(adjustment.reporting_obligation_id, lease);
     validateBoundRows(adjustment);
@@ -766,6 +796,14 @@ ${managedDueArm}       )
     );
     return result.rows.map((row) => clone(row.data));
   }
+  async listAdjustmentMetadata(obligationId) {
+    const result = await this.query(
+      `SELECT data - 'rows' AS data FROM adcp_reporting_adjustments WHERE obligation_id = $1
+        ORDER BY adjustment_number, adjustment_id`,
+      [obligationId]
+    );
+    return result.rows.map((row) => clone(row.data));
+  }
   async putConsumerStatus(status) {
     const obligation = await this.getObligation(status.reporting_obligation_id);
     if (!obligation) throw new Error("Reporting consumer status obligation is unavailable");

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

@@ -686,6 +686,26 @@ ${managedDueArm}       )
       [id, accountId]
     );
   }
+  async readRevisionRows(input) {
+    if (!Number.isSafeInteger(input.offset) || input.offset < 0 || !Number.isSafeInteger(input.limit) || input.limit < 1) {
+      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(
+                revision.data->'rows',
+                '$[$from to $to]',
+                jsonb_build_object('from', $3::bigint, 'to', $3::bigint + $4::bigint - 1)
+              ) 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`,
+      [input.reporting_revision_id, input.account_id, input.offset, input.limit]
+    );
+    const row = result.rows[0];
+    if (!row) return null;
+    return { rows: clone(row.rows), total: Number(row.total) };
+  }
   async listRevisions(obligationId) {
     const result = await this.query(
       `SELECT data FROM adcp_reporting_revisions WHERE obligation_id = $1
@@ -694,6 +714,16 @@ ${managedDueArm}       )
     );
     return result.rows.map((row) => clone(row.data));
   }
+  async listRevisionMetadata(obligationId, accountId) {
+    const result = await this.query(
+      `SELECT revision.data - 'rows' AS data FROM adcp_reporting_revisions revision
+         JOIN adcp_reporting_obligations obligation ON obligation.obligation_id = revision.obligation_id
+        WHERE revision.obligation_id = $1 AND ($2::text IS NULL OR obligation.account_id = $2)
+        ORDER BY revision.revision_number, revision.revision_id`,
+      [obligationId, accountId ?? null]
+    );
+    return result.rows.map((row) => clone(row.data));
+  }
   async commitAdjustment(adjustment, lease) {
     assertLeaseTarget(adjustment.reporting_obligation_id, lease);
     validateBoundRows(adjustment);
@@ -757,6 +787,14 @@ ${managedDueArm}       )
     );
     return result.rows.map((row) => clone(row.data));
   }
+  async listAdjustmentMetadata(obligationId) {
+    const result = await this.query(
+      `SELECT data - 'rows' AS data FROM adcp_reporting_adjustments WHERE obligation_id = $1
+        ORDER BY adjustment_number, adjustment_id`,
+      [obligationId]
+    );
+    return result.rows.map((row) => clone(row.data));
+  }
   async putConsumerStatus(status) {
     const obligation = await this.getObligation(status.reporting_obligation_id);
     if (!obligation) throw new Error("Reporting consumer status obligation is unavailable");

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

@@ -32,6 +32,7 @@ var import_source = require('../source/index.js');
 var import_coverage = require('./coverage.js');
 var import_schedule = require('./schedule.js');
 var import_lifecycle = require('./lifecycle.js');
+var import_revision_metadata = require('./revision-metadata.js');
 const DEFAULT_LEASE_MS = 3e5;
 const EXECUTION_DEADLINE_MS = 24e4;
 const DEFAULT_SETTLEMENT_GRACE_MS = 1e4;
@@ -268,8 +269,8 @@ function createReportingProducer(options) {
               );
             }
           }
-          const previous = await options.store.listRevisions(obligation.reporting_obligation_id);
-          const adjustments = await options.store.listAdjustments(obligation.reporting_obligation_id);
+          const previous = await (0, import_revision_metadata.listRevisionMetadataFromStore)(options.store, obligation.reporting_obligation_id);
+          const adjustments = await (0, import_revision_metadata.listAdjustmentMetadataFromStore)(options.store, obligation.reporting_obligation_id);
           const publicationCount = previous.length + adjustments.length;
           if (publicationCount > 0) {
             const scheduledAt = nextPublicationAt(obligation, publicationCount);

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

@@ -28,6 +28,7 @@ import {
   reconcileReportingStatusLifecycleV1,
   retryReportingStatusNotificationsV1
 } from "./lifecycle.mjs";
+import { listAdjustmentMetadataFromStore, listRevisionMetadataFromStore } from "./revision-metadata.mjs";
 const DEFAULT_LEASE_MS = 3e5;
 const EXECUTION_DEADLINE_MS = 24e4;
 const DEFAULT_SETTLEMENT_GRACE_MS = 1e4;
@@ -264,8 +265,8 @@ function createReportingProducer(options) {
               );
             }
           }
-          const previous = await options.store.listRevisions(obligation.reporting_obligation_id);
-          const adjustments = await options.store.listAdjustments(obligation.reporting_obligation_id);
+          const previous = await listRevisionMetadataFromStore(options.store, obligation.reporting_obligation_id);
+          const adjustments = await listAdjustmentMetadataFromStore(options.store, obligation.reporting_obligation_id);
           const publicationCount = previous.length + adjustments.length;
           if (publicationCount > 0) {
             const scheduledAt = nextPublicationAt(obligation, publicationCount);

package/dist/lib/reporting/ledger/revision-metadata.d.mts

@@ -0,0 +1,17 @@
+import type { ReportingLedgerAdjustmentMetadataV1, ReportingLedgerRevisionMetadataV1, ReportingLedgerStore, ReportingRevisionRowsPageV1, ReportingRevisionRowsReadV1 } from './types.mjs';
+/**
+ * Row-free revision listing for paths that only need identity, finality,
+ * supersession, binding and wire metadata. Prefers the store's
+ * `listRevisionMetadata`; a store without it is read through `listRevisions`
+ * and its rows are dropped before they reach the caller.
+ */
+export declare function listRevisionMetadataFromStore(store: Pick<ReportingLedgerStore, 'listRevisions' | 'listRevisionMetadata'>, reporting_obligation_id: string): Promise<ReportingLedgerRevisionMetadataV1[]>;
+/** Row-free counterpart of {@link listRevisionMetadataFromStore} for adjustments. */
+export declare function listAdjustmentMetadataFromStore(store: Pick<ReportingLedgerStore, 'listAdjustments' | 'listAdjustmentMetadata'>, reporting_obligation_id: string): Promise<ReportingLedgerAdjustmentMetadataV1[]>;
+/** Account-scoped revision metadata, preferring the store's row-free read. */
+export declare function getRevisionMetadataFromStore(store: Pick<ReportingLedgerStore, 'getRevision' | 'getRevisionMetadata'>, reporting_revision_id: string, account_id: string): Promise<ReportingLedgerRevisionMetadataV1 | null>;
+/**
+ * One page of a revision's rows. Prefers the store's paged reader; otherwise
+ * loads the revision through `getRevision` and slices it.
+ */
+export declare function readRevisionRowsFromStore(store: Pick<ReportingLedgerStore, 'getRevision' | 'readRevisionRows'>, input: ReportingRevisionRowsReadV1): Promise<ReportingRevisionRowsPageV1 | null>;

package/dist/lib/reporting/ledger/revision-metadata.d.ts

@@ -0,0 +1,17 @@
+import type { ReportingLedgerAdjustmentMetadataV1, ReportingLedgerRevisionMetadataV1, ReportingLedgerStore, ReportingRevisionRowsPageV1, ReportingRevisionRowsReadV1 } from './types';
+/**
+ * Row-free revision listing for paths that only need identity, finality,
+ * supersession, binding and wire metadata. Prefers the store's
+ * `listRevisionMetadata`; a store without it is read through `listRevisions`
+ * and its rows are dropped before they reach the caller.
+ */
+export declare function listRevisionMetadataFromStore(store: Pick<ReportingLedgerStore, 'listRevisions' | 'listRevisionMetadata'>, reporting_obligation_id: string): Promise<ReportingLedgerRevisionMetadataV1[]>;
+/** Row-free counterpart of {@link listRevisionMetadataFromStore} for adjustments. */
+export declare function listAdjustmentMetadataFromStore(store: Pick<ReportingLedgerStore, 'listAdjustments' | 'listAdjustmentMetadata'>, reporting_obligation_id: string): Promise<ReportingLedgerAdjustmentMetadataV1[]>;
+/** Account-scoped revision metadata, preferring the store's row-free read. */
+export declare function getRevisionMetadataFromStore(store: Pick<ReportingLedgerStore, 'getRevision' | 'getRevisionMetadata'>, reporting_revision_id: string, account_id: string): Promise<ReportingLedgerRevisionMetadataV1 | null>;
+/**
+ * One page of a revision's rows. Prefers the store's paged reader; otherwise
+ * loads the revision through `getRevision` and slices it.
+ */
+export declare function readRevisionRowsFromStore(store: Pick<ReportingLedgerStore, 'getRevision' | 'readRevisionRows'>, input: ReportingRevisionRowsReadV1): Promise<ReportingRevisionRowsPageV1 | null>;

package/dist/lib/reporting/ledger/revision-metadata.js

@@ -0,0 +1,71 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var revision_metadata_exports = {};
+__export(revision_metadata_exports, {
+  getRevisionMetadataFromStore: () => getRevisionMetadataFromStore,
+  listAdjustmentMetadataFromStore: () => listAdjustmentMetadataFromStore,
+  listRevisionMetadataFromStore: () => listRevisionMetadataFromStore,
+  readRevisionRowsFromStore: () => readRevisionRowsFromStore
+});
+module.exports = __toCommonJS(revision_metadata_exports);
+async function listRevisionMetadataFromStore(store, reporting_obligation_id) {
+  if (typeof store.listRevisionMetadata === "function") {
+    return store.listRevisionMetadata(reporting_obligation_id);
+  }
+  const revisions = await store.listRevisions(reporting_obligation_id);
+  return revisions.map(({ rows: _rows, ...metadata }) => metadata);
+}
+async function listAdjustmentMetadataFromStore(store, reporting_obligation_id) {
+  if (typeof store.listAdjustmentMetadata === "function") {
+    return store.listAdjustmentMetadata(reporting_obligation_id);
+  }
+  const adjustments = await store.listAdjustments(reporting_obligation_id);
+  return adjustments.map(({ rows: _rows, ...metadata }) => metadata);
+}
+async function getRevisionMetadataFromStore(store, reporting_revision_id, account_id) {
+  if (typeof store.getRevisionMetadata === "function") {
+    return store.getRevisionMetadata(reporting_revision_id, account_id);
+  }
+  const revision = await store.getRevision(reporting_revision_id, account_id);
+  if (!revision) return null;
+  const { rows: _rows, ...metadata } = revision;
+  return metadata;
+}
+async function readRevisionRowsFromStore(store, input) {
+  if (!Number.isSafeInteger(input.offset) || input.offset < 0) {
+    throw new RangeError("Reporting row page offset must be a non-negative integer");
+  }
+  if (!Number.isSafeInteger(input.limit) || input.limit < 1) {
+    throw new RangeError("Reporting row page limit must be a positive integer");
+  }
+  if (typeof store.readRevisionRows === "function") return store.readRevisionRows(input);
+  const revision = await store.getRevision(input.reporting_revision_id, input.account_id);
+  if (!revision) return null;
+  return {
+    rows: revision.rows.slice(input.offset, input.offset + input.limit),
+    total: revision.rows.length
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getRevisionMetadataFromStore,
+  listAdjustmentMetadataFromStore,
+  listRevisionMetadataFromStore,
+  readRevisionRowsFromStore
+});

package/dist/lib/reporting/ledger/revision-metadata.mjs

@@ -0,0 +1,44 @@
+async function listRevisionMetadataFromStore(store, reporting_obligation_id) {
+  if (typeof store.listRevisionMetadata === "function") {
+    return store.listRevisionMetadata(reporting_obligation_id);
+  }
+  const revisions = await store.listRevisions(reporting_obligation_id);
+  return revisions.map(({ rows: _rows, ...metadata }) => metadata);
+}
+async function listAdjustmentMetadataFromStore(store, reporting_obligation_id) {
+  if (typeof store.listAdjustmentMetadata === "function") {
+    return store.listAdjustmentMetadata(reporting_obligation_id);
+  }
+  const adjustments = await store.listAdjustments(reporting_obligation_id);
+  return adjustments.map(({ rows: _rows, ...metadata }) => metadata);
+}
+async function getRevisionMetadataFromStore(store, reporting_revision_id, account_id) {
+  if (typeof store.getRevisionMetadata === "function") {
+    return store.getRevisionMetadata(reporting_revision_id, account_id);
+  }
+  const revision = await store.getRevision(reporting_revision_id, account_id);
+  if (!revision) return null;
+  const { rows: _rows, ...metadata } = revision;
+  return metadata;
+}
+async function readRevisionRowsFromStore(store, input) {
+  if (!Number.isSafeInteger(input.offset) || input.offset < 0) {
+    throw new RangeError("Reporting row page offset must be a non-negative integer");
+  }
+  if (!Number.isSafeInteger(input.limit) || input.limit < 1) {
+    throw new RangeError("Reporting row page limit must be a positive integer");
+  }
+  if (typeof store.readRevisionRows === "function") return store.readRevisionRows(input);
+  const revision = await store.getRevision(input.reporting_revision_id, input.account_id);
+  if (!revision) return null;
+  return {
+    rows: revision.rows.slice(input.offset, input.offset + input.limit),
+    total: revision.rows.length
+  };
+}
+export {
+  getRevisionMetadataFromStore,
+  listAdjustmentMetadataFromStore,
+  listRevisionMetadataFromStore,
+  readRevisionRowsFromStore
+};

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

@@ -0,0 +1,128 @@
+/**
+ * Canonical JSONL row encoding for reporting revisions (shared SDK
+ * persistence contract, `reporting-row-storage` v1).
+ *
+ * Rows are stored as `JCS(row) + "\n"` in ordinal order. JCS escapes newline
+ * characters inside strings, so the `0x0A` byte only ever separates rows.
+ * Rows are grouped into segments (the unit of verification and paged reads)
+ * and chunks (the unit of storage). Boundaries are fixed by the contract so
+ * every SDK produces byte-identical chunks and manifests for the same rows:
+ *
+ * - a new chunk starts when the current chunk holds
+ *   {@link REPORTING_ROW_CHUNK_MAX_ROWS} rows, or when appending the next row
+ *   would exceed {@link REPORTING_ROW_CHUNK_MAX_BYTES} canonical bytes;
+ * - segments restart at each chunk boundary and close every
+ *   {@link REPORTING_ROW_SEGMENT_MAX_ROWS} rows.
+ *
+ * A row larger than the chunk byte limit forms its own segment and chunk.
+ * Digests always cover uncompressed canonical bytes.
+ */
+export declare const REPORTING_ROW_ENCODING_V1: "adcp_canonical_jsonl_v1";
+export declare const REPORTING_ROW_SEGMENT_MAX_ROWS = 500;
+export declare const REPORTING_ROW_CHUNK_MAX_SEGMENTS = 20;
+export declare const REPORTING_ROW_CHUNK_MAX_ROWS: number;
+export declare const REPORTING_ROW_CHUNK_MAX_BYTES: number;
+export type ReportingRowEncodingErrorCode = 'INVALID_ROW' | 'MANIFEST_MISMATCH' | 'CHUNK_INTEGRITY_FAILED' | 'ENVELOPE_INTEGRITY_FAILED';
+export declare class ReportingRowEncodingError extends Error {
+    readonly code: ReportingRowEncodingErrorCode;
+    constructor(code: ReportingRowEncodingErrorCode, detail: string);
+}
+export declare function isReportingRowEncodingError(error: unknown): error is ReportingRowEncodingError;
+export interface ReportingRowSegmentManifestV1 {
+    first_ordinal: number;
+    row_count: number;
+    /** Offset of the segment within its chunk's uncompressed canonical bytes. */
+    byte_offset: number;
+    byte_count: number;
+    sha256: string;
+}
+export interface ReportingRowChunkManifestV1 {
+    chunk_index: number;
+    first_ordinal: number;
+    row_count: number;
+    byte_count: number;
+    sha256: string;
+    segments: ReportingRowSegmentManifestV1[];
+}
+export interface ReportingRowChunkV1 {
+    manifest: ReportingRowChunkManifestV1;
+    /** Uncompressed canonical JSONL bytes. */
+    bytes: Buffer;
+}
+export interface ReportingEncodedRowsV1 {
+    encoding: typeof REPORTING_ROW_ENCODING_V1;
+    rowCount: number;
+    /** Total canonical JSONL bytes across all chunks. */
+    byteCount: number;
+    chunks: ReportingRowChunkV1[];
+    manifests: ReportingRowChunkManifestV1[];
+    /** `sha256(JCS(manifests))`; bound immutably on the revision header. */
+    rowManifestSha256: string;
+}
+export interface ReportingRevisionEnvelopeInputV1 {
+    reporting_revision_id: string;
+    row_count: number;
+    control_totals: readonly unknown[];
+}
+export interface ReportingRevisionEnvelopeDigestV1 {
+    sha256: string;
+    /** Byte length of the canonical envelope; equals `binding.byteCount`. */
+    byteCount: number;
+}
+/**
+ * Canonicalize one row for storage. Refuses values whose canonical bytes are
+ * not portable across conforming JCS implementations: non-plain objects,
+ * non-finite numbers, integers outside ±(2^53 − 1), and lone surrogates.
+ */
+export declare function canonicalReportingRowV1(row: unknown, ordinal?: number): string;
+/** Encode rows into contract-fixed canonical JSONL chunks and manifests. */
+export declare function encodeReportingRowsV1(rows: readonly unknown[]): ReportingEncodedRowsV1;
+/** `sha256(JCS(manifests))` over the ordered chunk manifests, locators excluded. */
+export declare function reportingRowManifestSha256V1(manifests: readonly ReportingRowChunkManifestV1[]): string;
+/**
+ * Verify that a manifest set is internally consistent and matches the
+ * header's committed `row_manifest_sha256` and `row_count`. Ordinals must be
+ * contiguous from zero, chunk and segment boundaries must follow the contract
+ * limits, and segment byte ranges must tile their chunk exactly.
+ */
+export declare function verifyReportingRowManifestsV1(manifests: readonly ReportingRowChunkManifestV1[], expected: {
+    rowCount: number;
+    rowManifestSha256: string;
+}): void;
+/**
+ * Verify a whole chunk's canonical bytes against its manifest: total digest,
+ * byte count, and every segment's digest and line count.
+ */
+export declare function verifyReportingRowChunkV1(manifest: ReportingRowChunkManifestV1, bytes: Uint8Array): void;
+/**
+ * Verify and decode a contiguous range of segments `[fromSegment, toSegment]`
+ * (inclusive). `bytes` must hold exactly those segments' canonical bytes,
+ * starting at the first segment's `byte_offset` — the shape returned by a
+ * ranged object read. Rows are released only after every segment verifies.
+ */
+export declare function decodeVerifiedReportingRowSegmentsV1(manifest: ReportingRowChunkManifestV1, segmentRange: readonly [fromSegment: number, toSegment: number], bytes: Uint8Array): Record<string, unknown>[];
+/**
+ * Streaming hasher for the protocol revision binding
+ * `sha256(JCS({reporting_revision_id, row_count, control_totals, reporting_rows}))`.
+ * Feed verified chunk bytes in order; rows are never parsed.
+ */
+export declare function createReportingRevisionEnvelopeHasherV1(envelope: ReportingRevisionEnvelopeInputV1): {
+    update(chunkBytes: Uint8Array): void;
+    digest(): ReportingRevisionEnvelopeDigestV1;
+};
+/** Envelope digest over already-encoded chunk bytes. */
+export declare function reportingRevisionEnvelopeDigestV1(envelope: ReportingRevisionEnvelopeInputV1, chunks: Iterable<Uint8Array>): ReportingRevisionEnvelopeDigestV1;
+/** Streaming hasher for digest profile `rows_v1`: `sha256(JCS(rows))`. */
+export declare function createReportingRowsOnlyHasherV1(rowCount: number): {
+    update(chunkBytes: Uint8Array): void;
+    digest(): ReportingRevisionEnvelopeDigestV1;
+};
+/**
+ * Throw unless the canonical chunks reproduce the header's committed revision
+ * binding. Used at write time (proof that chunks and envelope agree) and for
+ * full-revision reads.
+ */
+export declare function assertReportingRevisionEnvelopeV1(envelope: ReportingRevisionEnvelopeInputV1, chunks: Iterable<Uint8Array>, expected: {
+    sha256: string;
+    byteCount?: number;
+}): void;