@adcp/sdk 16.0.0-beta.2 → 16.0.0-beta.4

package/dist/lib/protocols/responseSizeLimit.mjs

@@ -5,52 +5,116 @@ const __dirname = __adcpDirname(__adcpFileURLToPath(import.meta.url));
 const require2 = __adcpCreateRequire(import.meta.url);
 import { globalAsyncLocalStorage } from "../utils/global-async-local-storage.mjs";
 import { ResponseTooLargeError } from "../errors/index.mjs";
+import { sanitizeTransportUrl } from "./transportDiagnostics.mjs";
+const DEFAULT_MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+const SSE_CUMULATIVE_BUDGET_MULTIPLIER = 2;
 const responseSizeLimitStorage = globalAsyncLocalStorage("responseSizeLimit");
+function resolveResponseSizeCap(maxResponseBytes) {
+  if (maxResponseBytes === void 0) return DEFAULT_MAX_RESPONSE_BYTES;
+  if (maxResponseBytes === 0) return null;
+  if (!Number.isFinite(maxResponseBytes) || maxResponseBytes < 0) return DEFAULT_MAX_RESPONSE_BYTES;
+  return maxResponseBytes;
+}
+function newSlot(maxResponseBytes) {
+  const resolved = resolveResponseSizeCap(maxResponseBytes);
+  if (resolved === null) return { maxResponseBytes: null };
+  const enclosing = responseSizeLimitStorage.getStore();
+  const limit = sseBudgetFor(resolved);
+  return {
+    // Nesting narrows both numbers. `?? resolved` deliberately also covers an
+    // enclosing opt-out (`null`): an inner scope that asks for a cap is the
+    // more specific instruction, so it still gets one.
+    maxResponseBytes: Math.min(resolved, enclosing?.maxResponseBytes ?? resolved),
+    streamLimit: Math.min(limit, enclosing?.streamLimit ?? limit),
+    streamMeter: enclosing?.streamMeter ?? { consumed: 0 }
+  };
+}
+function sseBudgetFor(maxResponseBytes) {
+  return Math.min(maxResponseBytes * SSE_CUMULATIVE_BUDGET_MULTIPLIER, Number.MAX_SAFE_INTEGER);
+}
+function responseSizeCapCacheKey() {
+  const slot = responseSizeLimitStorage.getStore();
+  const cap = slot ? slot.maxResponseBytes : DEFAULT_MAX_RESPONSE_BYTES;
+  return `max-response-bytes:${cap === null ? "off" : cap}`;
+}
 function withResponseSizeLimit(maxResponseBytes, fn) {
-  if (!maxResponseBytes || !Number.isFinite(maxResponseBytes) || maxResponseBytes <= 0) {
+  if (maxResponseBytes === void 0 && responseSizeLimitStorage.getStore()) {
     return fn();
   }
-  return responseSizeLimitStorage.run({ maxResponseBytes }, fn);
+  const slot = newSlot(maxResponseBytes);
+  return responseSizeLimitStorage.run(slot, () => rethrowRecordedViolation(slot, fn));
+}
+async function rethrowRecordedViolation(slot, fn) {
+  try {
+    return await fn();
+  } catch (error) {
+    const violation = slot.violation;
+    if (!violation || error instanceof ResponseTooLargeError) throw error;
+    const surfaced = new ResponseTooLargeError(
+      violation.limit,
+      violation.bytesRead,
+      violation.url,
+      violation.contentLengthHeader
+    );
+    Object.defineProperty(surfaced, "cause", { value: error, configurable: true });
+    throw surfaced;
+  }
+}
+function recordViolation(slot, error) {
+  if (slot && !slot.violation) slot.violation = error;
+  return error;
 }
 function urlOfInput(input) {
   if (typeof input === "string") return input;
   if (input instanceof URL) return input.toString();
   return input.url;
 }
-function redactUrlForError(url) {
-  try {
-    const parsed = new URL(url);
-    parsed.search = "";
-    return parsed.toString();
-  } catch {
-    return url;
-  }
-}
-function withIdentityEncoding(init) {
-  const headers = new Headers(init?.headers);
-  if (!headers.has("accept-encoding")) {
-    headers.set("accept-encoding", "identity");
-  }
-  return { ...init ?? {}, headers };
-}
 function wrapFetchWithSizeLimit(upstream) {
   const wrapped = async (input, init) => {
     const slot = responseSizeLimitStorage.getStore();
-    if (!slot) return upstream(input, init);
-    const response = await upstream(input, withIdentityEncoding(init));
-    return enforceSizeLimit(response, slot.maxResponseBytes, redactUrlForError(urlOfInput(input)));
+    const maxBytes = slot ? slot.maxResponseBytes : DEFAULT_MAX_RESPONSE_BYTES;
+    if (maxBytes === null) return upstream(input, init);
+    const response = await upstream(input, init);
+    if (NULL_BODY_STATUSES.has(response.status)) return response;
+    const skipDeclaredLength = methodOf(input, init) === "HEAD";
+    const url = sanitizeTransportUrl(urlOfInput(input));
+    if (isEventStream(response)) {
+      const connectionScoped = methodOf(input, init) === "GET";
+      const { limit, meter } = streamBudgetFor(connectionScoped, slot, maxBytes);
+      return enforceEventStreamLimit(
+        response,
+        maxBytes,
+        limit,
+        meter,
+        url,
+        connectionScoped ? void 0 : slot,
+        skipDeclaredLength
+      );
+    }
+    return enforceSizeLimit(response, maxBytes, url, slot, skipDeclaredLength);
   };
   return wrapped;
 }
-function enforceSizeLimit(response, maxBytes, url) {
-  if (response.headers.get("content-type")?.toLowerCase().startsWith("text/event-stream")) {
-    return response;
-  }
-  const declared = parseContentLength(response.headers.get("content-length"));
+function streamBudgetFor(connectionScoped, slot, maxBytes) {
+  if (connectionScoped) return { limit: sseBudgetFor(maxBytes), meter: { consumed: 0 } };
+  return {
+    limit: slot?.streamLimit ?? sseBudgetFor(maxBytes),
+    meter: slot?.streamMeter ?? { consumed: 0 }
+  };
+}
+function methodOf(input, init) {
+  const method = init?.method ?? (typeof Request !== "undefined" && input instanceof Request ? input.method : "GET");
+  return method.toUpperCase();
+}
+const NULL_BODY_STATUSES = /* @__PURE__ */ new Set([101, 103, 204, 205, 304]);
+function isEventStream(response) {
+  return response.headers.get("content-type")?.toLowerCase().startsWith("text/event-stream") === true;
+}
+function enforceSizeLimit(response, maxBytes, url, slot, skipDeclaredLength = false) {
+  const declared = skipDeclaredLength ? void 0 : parseContentLength(response.headers.get("content-length"));
   if (declared !== void 0 && declared > maxBytes) {
-    response.body?.cancel().catch(() => {
-    });
-    throw new ResponseTooLargeError(maxBytes, 0, url, declared);
+    cancelBody(response);
+    throw recordViolation(slot, new ResponseTooLargeError(maxBytes, 0, url, declared));
   }
   if (!response.body) return response;
   let bytesRead = 0;
@@ -58,13 +122,107 @@ function enforceSizeLimit(response, maxBytes, url) {
     transform(chunk, controller) {
       bytesRead += chunk.byteLength;
       if (bytesRead > maxBytes) {
-        controller.error(new ResponseTooLargeError(maxBytes, bytesRead, url));
+        controller.error(recordViolation(slot, new ResponseTooLargeError(maxBytes, bytesRead, url)));
         return;
       }
       controller.enqueue(chunk);
     }
   });
-  return new Response(response.body.pipeThrough(counter), {
+  return respondWith(response, response.body.pipeThrough(counter));
+}
+const CR = 13;
+const LF = 10;
+function enforceEventStreamLimit(response, maxBytes, streamLimit, meter, url, slot, skipDeclaredLength = false) {
+  const remaining = streamLimit - meter.consumed;
+  const declared = skipDeclaredLength ? void 0 : parseContentLength(response.headers.get("content-length"));
+  if (declared !== void 0 && declared > remaining) {
+    cancelBody(response);
+    throw recordViolation(slot, new ResponseTooLargeError(streamLimit, meter.consumed, url, declared));
+  }
+  if (!response.body) return response;
+  let bytesInEvent = 0;
+  let lineEndings = 0;
+  let pendingCR = false;
+  let separatorTail = false;
+  let pendingReset = false;
+  const counter = new TransformStream({
+    transform(chunk, controller) {
+      meter.consumed += chunk.byteLength;
+      if (meter.consumed > streamLimit) {
+        controller.error(recordViolation(slot, new ResponseTooLargeError(streamLimit, meter.consumed, url)));
+        return;
+      }
+      if (chunk.length === 0) {
+        controller.enqueue(chunk);
+        return;
+      }
+      if (chunk.indexOf(LF) === -1 && chunk.indexOf(CR) === -1) {
+        if (pendingReset) {
+          pendingReset = false;
+          separatorTail = false;
+          bytesInEvent = 0;
+        }
+        bytesInEvent += chunk.length;
+        lineEndings = 0;
+        pendingCR = false;
+        if (bytesInEvent > maxBytes) {
+          controller.error(recordViolation(slot, new ResponseTooLargeError(maxBytes, bytesInEvent, url)));
+          return;
+        }
+        controller.enqueue(chunk);
+        return;
+      }
+      for (let i = 0; i < chunk.length; i += 1) {
+        const byte = chunk[i];
+        if (pendingReset) {
+          pendingReset = false;
+          if (separatorTail && byte === LF) {
+            separatorTail = false;
+            pendingCR = false;
+            bytesInEvent += 1;
+            if (bytesInEvent > maxBytes) {
+              controller.error(recordViolation(slot, new ResponseTooLargeError(maxBytes, bytesInEvent, url)));
+              return;
+            }
+            bytesInEvent = 0;
+            continue;
+          }
+          separatorTail = false;
+          bytesInEvent = 0;
+        }
+        bytesInEvent += 1;
+        if (byte === CR) {
+          lineEndings += 1;
+          pendingCR = true;
+        } else if (byte === LF) {
+          if (!pendingCR) lineEndings += 1;
+          pendingCR = false;
+        } else {
+          lineEndings = 0;
+          pendingCR = false;
+        }
+        if (bytesInEvent > maxBytes) {
+          controller.error(recordViolation(slot, new ResponseTooLargeError(maxBytes, bytesInEvent, url)));
+          return;
+        }
+        if (lineEndings >= 2) {
+          lineEndings = 0;
+          pendingReset = true;
+          separatorTail = pendingCR;
+          pendingCR = false;
+        }
+      }
+      controller.enqueue(chunk);
+    }
+  });
+  return respondWith(response, response.body.pipeThrough(counter));
+}
+function cancelBody(response) {
+  response.body?.cancel().catch(() => {
+  });
+}
+function respondWith(response, body) {
+  return new Response(body, {
     status: response.status,
     statusText: response.statusText,
     headers: response.headers
@@ -78,6 +236,9 @@ function parseContentLength(value) {
   return Number.isFinite(parsed) ? parsed : void 0;
 }
 export {
+  DEFAULT_MAX_RESPONSE_BYTES,
+  SSE_CUMULATIVE_BUDGET_MULTIPLIER,
+  responseSizeCapCacheKey,
   responseSizeLimitStorage,
   withResponseSizeLimit,
   wrapFetchWithSizeLimit

package/dist/lib/reporting/consumer-runtime.js

@@ -23,6 +23,7 @@ __export(consumer_runtime_exports, {
 });
 module.exports = __toCommonJS(consumer_runtime_exports);
 var import_jcs = require('../utils/jcs.js');
+var import_pagination = require('./pagination.js');
 var import_reconciliation = require('./reconciliation.js');
 const DEFAULT_POLL_INTERVAL_MS = 6e4;
 const DEFAULT_LEASE_MS = 3e4;
@@ -59,7 +60,7 @@ async function drainReportingChanges(options, stopAfterChangeDetected) {
           ...options.request,
           view: "periods",
           changes_after: options.changesAfter,
-          ...cursor ? { pagination: { cursor } } : {}
+          pagination: { max_results: (0, import_pagination.reportingMaxPageSize)(), ...cursor ? { cursor } : {} }
         },
         { signal }
       ),

package/dist/lib/reporting/consumer-runtime.mjs

@@ -1,4 +1,5 @@
 import { canonicalJsonSha256 } from "../utils/jcs.mjs";
+import { reportingMaxPageSize } from "./pagination.mjs";
 import {
   ReportingReconciliationError,
   reconcileReporting
@@ -38,7 +39,7 @@ async function drainReportingChanges(options, stopAfterChangeDetected) {
           ...options.request,
           view: "periods",
           changes_after: options.changesAfter,
-          ...cursor ? { pagination: { cursor } } : {}
+          pagination: { max_results: reportingMaxPageSize(), ...cursor ? { cursor } : {} }
         },
         { signal }
       ),

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

@@ -31,12 +31,13 @@ module.exports = __toCommonJS(handler_exports);
 var import_node_crypto = require("node:crypto");
 var import_version = require('../../version.js');
 var import_async_outcome = require('../../server/decisioning/async-outcome.js');
+var import_schema_loader = require('../../validation/schema-loader.js');
 var import_source = require('../source/index.js');
 var import_coverage = require('./coverage.js');
 var import_health = require('./health.js');
 var import_instant = require('./instant.js');
 var import_revision_metadata = require('./revision-metadata.js');
-var import_row_storage = require('./row-storage.js');
+var import_row_storage_errors = require('./row-storage-errors.js');
 var import_schedule = require('./schedule.js');
 var import_types = require('./types.js');
 function createReportingStatusHandler(store, options) {
@@ -48,6 +49,7 @@ function createReportingStatusHandler(store, options) {
     )
   );
   const activeReadsByAccount = /* @__PURE__ */ new Map();
+  reportingPageBounds();
   return async (request, context) => {
     const raw = request;
     const resolvedAccount = isRecord(context.account) ? context.account : {};
@@ -81,9 +83,7 @@ function createReportingStatusHandler(store, options) {
         ...typeof raw.changes_after === "string" ? { changes_after: raw.changes_after } : {},
         ...isRecord(raw.period) ? { period: raw.period } : {}
       };
-      const pagination = isRecord(raw.pagination) ? raw.pagination : {};
-      const limitValue = pagination.max_results ?? pagination.limit ?? 100;
-      const limit = typeof limitValue === "number" && Number.isFinite(limitValue) ? Math.max(1, Math.min(500, Math.trunc(limitValue))) : 100;
+      const { pageSize: limit, pagination } = reportingPagination(raw.pagination);
       const cursor = typeof pagination.cursor === "string" ? pagination.cursor : void 0;
       let snapshotId;
       if (cursor) {
@@ -99,7 +99,7 @@ function createReportingStatusHandler(store, options) {
         try {
           snapshot = await store.createSnapshot(query);
         } catch (error) {
-          if (error instanceof import_types.ReportingLedgerSnapshotUnavailableError || error instanceof ReportingReadCapacityError) {
+          if ((0, import_types.isReportingLedgerErrorNamed)(error, "ReportingLedgerSnapshotUnavailableError") || error instanceof ReportingReadCapacityError) {
             return lookupUnavailable(view);
           }
           if (isContinuityError(error)) return operationalUnavailable(view);
@@ -111,7 +111,7 @@ function createReportingStatusHandler(store, options) {
         try {
           page = await store.readSnapshotPage(snapshotId ?? snapshot.snapshotId, accountId, cursor, limit);
         } catch (error) {
-          if (error instanceof import_types.ReportingLedgerSnapshotUnavailableError || error instanceof ReportingReadCapacityError) {
+          if ((0, import_types.isReportingLedgerErrorNamed)(error, "ReportingLedgerSnapshotUnavailableError") || error instanceof ReportingReadCapacityError) {
             return lookupUnavailable(view);
           }
           if (isContinuityError(error)) return operationalUnavailable(view);
@@ -275,7 +275,7 @@ function createReportingStatusHandler(store, options) {
               else revisionRows = page2.rows;
             }
           } catch (error) {
-            if (error instanceof ReportingReadCapacityError || (0, import_row_storage.isReportingRowStoreError)(error)) {
+            if (error instanceof ReportingReadCapacityError || (0, import_row_storage_errors.isReportingRowStoreError)(error)) {
               return lookupUnavailable(view);
             }
             throw error;
@@ -412,7 +412,7 @@ function createReportingStatusHandler(store, options) {
         issues: issues.map(wireIssue)
       };
     } catch (error) {
-      if (error instanceof import_health.ReportingLedgerIssueIntegrityError) return operationalUnavailable(view);
+      if ((0, import_types.isReportingLedgerErrorNamed)(error, "ReportingLedgerIssueIntegrityError")) return operationalUnavailable(view);
       throw error;
     } finally {
       releaseReadSlot();
@@ -420,6 +420,45 @@ function createReportingStatusHandler(store, options) {
   };
 }
 const REPORTING_STATUS_REVISION_VIEW_MAX_ROWS = 1e4;
+let pageBounds;
+function reportingPageBounds() {
+  if (pageBounds) return pageBounds;
+  const document = (0, import_schema_loader.getSchemaDocumentByRef)("core/pagination-request.json");
+  const field = document?.schema.properties?.max_results;
+  const { minimum, maximum, default: initial } = field ?? {};
+  if (!Number.isSafeInteger(minimum) || !Number.isSafeInteger(maximum) || !Number.isSafeInteger(initial) || minimum < 1 || maximum < minimum || initial < minimum || initial > maximum) {
+    throw new Error("The AdCP pagination-request schema does not define bounds for max_results");
+  }
+  pageBounds = Object.freeze({
+    minimum,
+    maximum,
+    default: initial
+  });
+  return pageBounds;
+}
+function reportingPagination(value) {
+  const bounds = reportingPageBounds();
+  if (value !== void 0 && !isRecord(value)) {
+    throw new import_async_outcome.AdcpError("VALIDATION_ERROR", { message: "pagination must be an object", field: "pagination" });
+  }
+  const pagination = value ?? {};
+  if (pagination.cursor !== void 0 && typeof pagination.cursor !== "string") {
+    throw new import_async_outcome.AdcpError("VALIDATION_ERROR", {
+      message: "pagination.cursor must be a string",
+      field: "pagination.cursor"
+    });
+  }
+  const size = pagination.max_results;
+  if (size === void 0) return { pageSize: bounds.default, pagination };
+  if (typeof size !== "number" || !Number.isInteger(size) || size < bounds.minimum || size > bounds.maximum) {
+    throw new import_async_outcome.AdcpError("VALIDATION_ERROR", {
+      message: `pagination.max_results must be an integer from ${bounds.minimum} to ${bounds.maximum}`,
+      field: "pagination.max_results",
+      suggestion: `Send an integer from ${bounds.minimum} to ${bounds.maximum}, or omit it for the default of ${bounds.default}.`
+    });
+  }
+  return { pageSize: size, pagination };
+}
 function reportingRevisionNotFound() {
   return new import_async_outcome.AdcpError("REFERENCE_NOT_FOUND", {
     message: "Reporting revision is unavailable",
@@ -432,6 +471,7 @@ function createReportingDeliveryHandler(store, options = {}) {
   if (legacyRevisionReader !== void 0 && typeof legacyRevisionReader !== "function") {
     throw new TypeError("legacyRevisionReader must be a function");
   }
+  reportingPageBounds();
   const activeReadsByAccount = /* @__PURE__ */ new Map();
   const readFromSdkLedger = async (request, context) => {
     const accountId = resolvedAccountId(context.account);
@@ -454,12 +494,11 @@ function createReportingDeliveryHandler(store, options = {}) {
           field: "reporting_revision_id"
         });
       }
+      const { pageSize: maxResults, pagination } = reportingPagination(raw.pagination);
       const revision = await (0, import_revision_metadata.getRevisionMetadataFromStore)(store, raw.reporting_revision_id, accountId);
       if (!revision) return SDK_REVISION_NOT_OWNED;
       const obligation = await store.getObligation(revision.reporting_obligation_id);
       if (!obligation || obligation.account.account_id !== accountId) return SDK_REVISION_NOT_OWNED;
-      const pagination = isRecord(raw.pagination) ? raw.pagination : {};
-      const maxResults = typeof pagination.max_results === "number" && Number.isFinite(pagination.max_results) ? Math.max(1, Math.min(500, Math.trunc(pagination.max_results))) : 100;
       const totalCount = revision.binding.rowCount;
       let offset = 0;
       if (typeof pagination.cursor === "string") {
@@ -485,7 +524,7 @@ function createReportingDeliveryHandler(store, options = {}) {
             ...context.signal ? { signal: context.signal } : {}
           });
         } catch (error) {
-          if ((0, import_row_storage.isReportingRowStoreError)(error)) {
+          if ((0, import_row_storage_errors.isReportingRowStoreError)(error)) {
             if (error.code === "ROWS_EXPIRED") throw reportingRevisionNotFound();
             throw new import_async_outcome.AdcpError("SERVICE_UNAVAILABLE", {
               message: "Reporting revision rows are temporarily unavailable"

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

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { ADCP_MAJOR_VERSION, ADCP_VERSION, toReleasePrecisionVersion } from "../../version.mjs";
 import { AdcpError } from "../../server/decisioning/async-outcome.mjs";
+import { getSchemaDocumentByRef } from "../../validation/schema-loader.mjs";
 import { canonicalJsonV1 } from "../source/index.mjs";
 import {
   evaluateReportingLedgerCoverageV1,
@@ -16,14 +17,13 @@ import {
   reportingEffectiveConsumerMismatchEscalationV1,
   projectReportingConsumerStatusMismatchV1,
   projectReportingObligationHealthV1,
-  projectReportingUnreadableRevisionHealthV1,
-  ReportingLedgerIssueIntegrityError
+  projectReportingUnreadableRevisionHealthV1
 } from "./health.mjs";
 import { compareReportingInstants } from "./instant.mjs";
 import { getRevisionMetadataFromStore, readRevisionRowsFromStore } from "./revision-metadata.mjs";
-import { isReportingRowStoreError } from "./row-storage.mjs";
+import { isReportingRowStoreError } from "./row-storage-errors.mjs";
 import { reportingPeriodSchedule } from "./schedule.mjs";
-import { ReportingLedgerSnapshotUnavailableError } from "./types.mjs";
+import { isReportingLedgerErrorNamed } from "./types.mjs";
 function createReportingStatusHandler(store, options) {
   const consumerMismatchEscalation = assertReportingConsumerMismatchEscalation(
     reportingEffectiveConsumerMismatchEscalationV1(
@@ -33,6 +33,7 @@ function createReportingStatusHandler(store, options) {
     )
   );
   const activeReadsByAccount = /* @__PURE__ */ new Map();
+  reportingPageBounds();
   return async (request, context) => {
     const raw = request;
     const resolvedAccount = isRecord(context.account) ? context.account : {};
@@ -66,9 +67,7 @@ function createReportingStatusHandler(store, options) {
         ...typeof raw.changes_after === "string" ? { changes_after: raw.changes_after } : {},
         ...isRecord(raw.period) ? { period: raw.period } : {}
       };
-      const pagination = isRecord(raw.pagination) ? raw.pagination : {};
-      const limitValue = pagination.max_results ?? pagination.limit ?? 100;
-      const limit = typeof limitValue === "number" && Number.isFinite(limitValue) ? Math.max(1, Math.min(500, Math.trunc(limitValue))) : 100;
+      const { pageSize: limit, pagination } = reportingPagination(raw.pagination);
       const cursor = typeof pagination.cursor === "string" ? pagination.cursor : void 0;
       let snapshotId;
       if (cursor) {
@@ -84,7 +83,7 @@ function createReportingStatusHandler(store, options) {
         try {
           snapshot = await store.createSnapshot(query);
         } catch (error) {
-          if (error instanceof ReportingLedgerSnapshotUnavailableError || error instanceof ReportingReadCapacityError) {
+          if (isReportingLedgerErrorNamed(error, "ReportingLedgerSnapshotUnavailableError") || error instanceof ReportingReadCapacityError) {
             return lookupUnavailable(view);
           }
           if (isContinuityError(error)) return operationalUnavailable(view);
@@ -96,7 +95,7 @@ function createReportingStatusHandler(store, options) {
         try {
           page = await store.readSnapshotPage(snapshotId ?? snapshot.snapshotId, accountId, cursor, limit);
         } catch (error) {
-          if (error instanceof ReportingLedgerSnapshotUnavailableError || error instanceof ReportingReadCapacityError) {
+          if (isReportingLedgerErrorNamed(error, "ReportingLedgerSnapshotUnavailableError") || error instanceof ReportingReadCapacityError) {
             return lookupUnavailable(view);
           }
           if (isContinuityError(error)) return operationalUnavailable(view);
@@ -397,7 +396,7 @@ function createReportingStatusHandler(store, options) {
         issues: issues.map(wireIssue)
       };
     } catch (error) {
-      if (error instanceof ReportingLedgerIssueIntegrityError) return operationalUnavailable(view);
+      if (isReportingLedgerErrorNamed(error, "ReportingLedgerIssueIntegrityError")) return operationalUnavailable(view);
       throw error;
     } finally {
       releaseReadSlot();
@@ -405,6 +404,45 @@ function createReportingStatusHandler(store, options) {
   };
 }
 const REPORTING_STATUS_REVISION_VIEW_MAX_ROWS = 1e4;
+let pageBounds;
+function reportingPageBounds() {
+  if (pageBounds) return pageBounds;
+  const document = getSchemaDocumentByRef("core/pagination-request.json");
+  const field = document?.schema.properties?.max_results;
+  const { minimum, maximum, default: initial } = field ?? {};
+  if (!Number.isSafeInteger(minimum) || !Number.isSafeInteger(maximum) || !Number.isSafeInteger(initial) || minimum < 1 || maximum < minimum || initial < minimum || initial > maximum) {
+    throw new Error("The AdCP pagination-request schema does not define bounds for max_results");
+  }
+  pageBounds = Object.freeze({
+    minimum,
+    maximum,
+    default: initial
+  });
+  return pageBounds;
+}
+function reportingPagination(value) {
+  const bounds = reportingPageBounds();
+  if (value !== void 0 && !isRecord(value)) {
+    throw new AdcpError("VALIDATION_ERROR", { message: "pagination must be an object", field: "pagination" });
+  }
+  const pagination = value ?? {};
+  if (pagination.cursor !== void 0 && typeof pagination.cursor !== "string") {
+    throw new AdcpError("VALIDATION_ERROR", {
+      message: "pagination.cursor must be a string",
+      field: "pagination.cursor"
+    });
+  }
+  const size = pagination.max_results;
+  if (size === void 0) return { pageSize: bounds.default, pagination };
+  if (typeof size !== "number" || !Number.isInteger(size) || size < bounds.minimum || size > bounds.maximum) {
+    throw new AdcpError("VALIDATION_ERROR", {
+      message: `pagination.max_results must be an integer from ${bounds.minimum} to ${bounds.maximum}`,
+      field: "pagination.max_results",
+      suggestion: `Send an integer from ${bounds.minimum} to ${bounds.maximum}, or omit it for the default of ${bounds.default}.`
+    });
+  }
+  return { pageSize: size, pagination };
+}
 function reportingRevisionNotFound() {
   return new AdcpError("REFERENCE_NOT_FOUND", {
     message: "Reporting revision is unavailable",
@@ -417,6 +455,7 @@ function createReportingDeliveryHandler(store, options = {}) {
   if (legacyRevisionReader !== void 0 && typeof legacyRevisionReader !== "function") {
     throw new TypeError("legacyRevisionReader must be a function");
   }
+  reportingPageBounds();
   const activeReadsByAccount = /* @__PURE__ */ new Map();
   const readFromSdkLedger = async (request, context) => {
     const accountId = resolvedAccountId(context.account);
@@ -439,12 +478,11 @@ function createReportingDeliveryHandler(store, options = {}) {
           field: "reporting_revision_id"
         });
       }
+      const { pageSize: maxResults, pagination } = reportingPagination(raw.pagination);
       const revision = await getRevisionMetadataFromStore(store, raw.reporting_revision_id, accountId);
       if (!revision) return SDK_REVISION_NOT_OWNED;
       const obligation = await store.getObligation(revision.reporting_obligation_id);
       if (!obligation || obligation.account.account_id !== accountId) return SDK_REVISION_NOT_OWNED;
-      const pagination = isRecord(raw.pagination) ? raw.pagination : {};
-      const maxResults = typeof pagination.max_results === "number" && Number.isFinite(pagination.max_results) ? Math.max(1, Math.min(500, Math.trunc(pagination.max_results))) : 100;
       const totalCount = revision.binding.rowCount;
       let offset = 0;
       if (typeof pagination.cursor === "string") {

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

@@ -1,9 +1,15 @@
 /**
- * Reliable Reporting ledger, row storage, change feed, managed-delivery runtime and router.
+ * Reliable Reporting protocol layer: the ledger store interface, the protocol handlers, the producer,
+ * status ingest, row encoding and the health, coverage and lifecycle helpers.
  *
- * Exports tagged `@experimental` (storage, rows, change feed, managed delivery, notification activity)
- * may change in minor releases. The protocol-facing handlers, producer, status ingest, health,
- * coverage, lifecycle and schedule helpers follow normal semver.
+ * Storage implementations (PostgreSQL ledger store, row storage, managed delivery, notification activity,
+ * the cloud providers and the BigQuery sink) live in `@adcp/reporting-storage`, which depends on this
+ * package. Nothing here imports it. A store from any package works with these handlers as long as it
+ * implements `ReportingLedgerStore`.
+ *
+ * The store, transaction, lease and row-read interfaces in `./types` are tagged `@experimental`: they
+ * change together with `@adcp/reporting-storage`, which is pre-1.0. The protocol-facing handlers,
+ * producer, status ingest, health, coverage and lifecycle helpers follow normal semver.
  *
  * Stability policy: https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
  *
@@ -13,18 +19,15 @@ export * from './types.mjs';
 export * from './health.mjs';
 export * from './coverage.mjs';
 export * from './lifecycle.mjs';
-export * from './postgres.mjs';
 export * from './producer.mjs';
 export * from './handler.mjs';
 export * from './status-ingest.mjs';
 export * from './consumer-status-identity.mjs';
-export * from './managed.mjs';
-export * from './managed-router.mjs';
-export * from './managed-postgres.mjs';
-export * from './object-writes.mjs';
-export * from './notification-activity.mjs';
 export * from './row-encoding.mjs';
-export * from './row-storage-migration.mjs';
-export * from './row-storage.mjs';
-export * from './row-storage-object.mjs';
-export * from './change-feed.mjs';
+export * from './row-storage-errors.mjs';
+export * from './receipts.mjs';
+export * from './offering-validation.mjs';
+export { compareReportingInstants } from './instant.mjs';
+export { isFrozenCalendarRulesMismatch, reportingPeriodDate, reportingPeriodSchedule } from './schedule.mjs';
+export { isReportingAdjustmentReceiptEvidence, isReportingReceiptEvidence, isReportingVerificationEvidence, } from '../evidence.mjs';
+export { isWellFormedUnicodeString } from '../../utils/well-formed-unicode.mjs';