@adcp/sdk 15.3.0 → 15.5.0

package/dist/lib/reporting/gcs/row-provider.js

@@ -0,0 +1,205 @@
+"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 row_provider_exports = {};
+__export(row_provider_exports, {
+  assertGcsReportingRowBucketPolicyV1: () => assertGcsReportingRowBucketPolicyV1,
+  createGcsReportingRowObjectProviderV1: () => createGcsReportingRowObjectProviderV1
+});
+module.exports = __toCommonJS(row_provider_exports);
+var import_node_crypto = require("node:crypto");
+var import_row_storage_errors = require('../ledger/row-storage-errors.js');
+var import_row_storage_provider_io = require('../ledger/row-storage-provider-io.js');
+const BUCKET = /^[a-z0-9][a-z0-9._-]{1,220}[a-z0-9]$/;
+const GENERATION = /^[1-9][0-9]{0,15}$/;
+const NONCURRENT_ONLY_CONDITIONS = ["numNewerVersions", "daysSinceNoncurrentTime", "noncurrentTimeBefore"];
+function status(error) {
+  if (!error || typeof error !== "object" || !("code" in error)) return void 0;
+  const code = Number(error.code);
+  return Number.isInteger(code) ? code : void 0;
+}
+function generationOf(metadata) {
+  const generation = metadata?.generation === void 0 ? "" : String(metadata.generation);
+  if (!GENERATION.test(generation) || !Number.isSafeInteger(Number(generation))) {
+    throw new import_row_storage_errors.ReportingRowStoreError("PROVIDER_UNAVAILABLE", "object generation is missing");
+  }
+  return generation;
+}
+function pinnedGeneration(nativeVersion) {
+  return typeof nativeVersion === "string" && GENERATION.test(nativeVersion) && Number.isSafeInteger(Number(nativeVersion)) ? nativeVersion : null;
+}
+function assertGcsReportingRowBucketPolicyV1(metadata, prefix) {
+  if (!metadata || typeof metadata !== "object") {
+    throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "bucket policy is unavailable");
+  }
+  if (metadata.iamConfiguration?.uniformBucketLevelAccess?.enabled !== true) {
+    throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "bucket must enable uniform bucket-level access");
+  }
+  if (metadata.iamConfiguration?.publicAccessPrevention !== "enforced") {
+    throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "bucket must enforce public access prevention");
+  }
+  for (const rule of metadata.lifecycle?.rule ?? []) {
+    if (rule?.action?.type !== "Delete") continue;
+    const condition = rule.condition ?? {};
+    if (condition.isLive === false) continue;
+    if (NONCURRENT_ONLY_CONDITIONS.some((name) => condition[name] !== void 0 && condition[name] !== null)) continue;
+    const prefixes = condition.matchesPrefix ?? [];
+    if (prefixes.length === 0 || prefixes.some((filter) => (0, import_row_storage_provider_io.reportingRowPrefixFilterOverlaps)(filter, prefix))) {
+      throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "a bucket lifecycle rule can delete live row objects");
+    }
+  }
+}
+function createGcsReportingRowObjectProviderV1(options) {
+  if (!options || typeof options !== "object") {
+    throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "GCS row provider options are required");
+  }
+  const clients = (0, import_row_storage_provider_io.reportingRowClientMap)(options.clients);
+  const isStorage = (value) => !!value && typeof value === "object" && typeof value.bucket === "function";
+  if (options.storage !== void 0 && !isStorage(options.storage) || [...clients.values()].some((client) => !isStorage(client)) || options.storage === void 0 && clients.size === 0) {
+    throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "inject an official Storage client as storage or clients");
+  }
+  const validateLocation = (location) => {
+    (0, import_row_storage_provider_io.assertReportingRowLocationKeys)(location, ["bucket"]);
+    if (!BUCKET.test(location.bucket) || location.bucket.includes("..")) {
+      throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "GCS bucket name is invalid");
+    }
+  };
+  const bucketFor = (input) => {
+    validateLocation(input.location);
+    return (0, import_row_storage_provider_io.selectReportingRowClient)(options.storage, clients, input.credentialRef).bucket(input.location.bucket);
+  };
+  const assertKey = (key) => {
+    if (typeof key !== "string" || key.length === 0 || Buffer.byteLength(key) > 1024) {
+      throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "object key is invalid");
+    }
+  };
+  return {
+    name: "gcs",
+    rangedReads: true,
+    validateLocation,
+    probe(input, context) {
+      return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
+        const bucket = bucketFor(input);
+        let metadata;
+        try {
+          [metadata] = await bucket.getMetadata();
+        } catch (error) {
+          const code = status(error);
+          if (code === 404) throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "bucket does not exist");
+          if (code === 401 || code === 403) {
+            throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "bucket policy cannot be read with this client");
+          }
+          throw error;
+        }
+        assertGcsReportingRowBucketPolicyV1(metadata, input.prefix);
+      });
+    },
+    putIfAbsent(input, context) {
+      return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
+        const bucket = bucketFor(input);
+        assertKey(input.key);
+        const file = bucket.file(input.key);
+        try {
+          const bytes = Buffer.from(input.bytes);
+          await file.save(bytes, {
+            resumable: false,
+            gzip: false,
+            // GCS verifies the declared MD5 before creating the object, so a corrupted upload
+            // is refused server-side. Client-side validation is off because on mismatch the
+            // client deletes the key without a generation precondition.
+            validation: false,
+            contentType: input.contentType,
+            metadata: {
+              contentType: input.contentType,
+              md5Hash: (0, import_node_crypto.createHash)("md5").update(bytes).digest("base64"),
+              cacheControl: "no-store",
+              metadata: { ...input.metadata }
+            },
+            preconditionOpts: { ifGenerationMatch: 0 }
+          });
+        } catch (error) {
+          if (status(error) !== 412) throw error;
+          context.signal.throwIfAborted();
+          const [existing] = await bucket.file(input.key).getMetadata();
+          return { created: false, nativeVersion: generationOf(existing) };
+        }
+        if (file.metadata?.generation !== void 0) {
+          return { created: true, nativeVersion: generationOf(file.metadata) };
+        }
+        const [created] = await file.getMetadata();
+        return { created: true, nativeVersion: generationOf(created) };
+      });
+    },
+    get(input, context) {
+      return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
+        const bucket = bucketFor(input);
+        assertKey(input.key);
+        (0, import_row_storage_provider_io.assertReportingRowReadBounds)(input);
+        const generation = pinnedGeneration(input.nativeVersion);
+        if (generation === null) return null;
+        const file = bucket.file(input.key, { generation });
+        try {
+          if (input.range?.length === 0) {
+            const [metadata] = await file.getMetadata();
+            if (input.range.offset > Number(metadata.size)) {
+              throw new import_row_storage_errors.ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "requested range exceeds the stored object");
+            }
+            return Buffer.alloc(0);
+          }
+          const stream = file.createReadStream({
+            // The client always sends `Accept-Encoding: gzip`; with `decompress: false`
+            // neither GCS nor the client transcodes, so these are the stored bytes.
+            decompress: false,
+            // Digests recorded in PostgreSQL verify every byte returned.
+            validation: false,
+            ...input.range ? { start: input.range.offset, end: input.range.offset + input.range.length - 1 } : {}
+          });
+          return await (0, import_row_storage_provider_io.readReportingRowStream)(stream, input.maxBytes, context.signal);
+        } catch (error) {
+          const code = status(error);
+          if (code === 404) return null;
+          if (code === 416) {
+            throw new import_row_storage_errors.ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "requested range exceeds the stored object");
+          }
+          throw error;
+        }
+      });
+    },
+    delete(input, context) {
+      return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
+        const bucket = bucketFor(input);
+        assertKey(input.key);
+        const generation = pinnedGeneration(input.nativeVersion);
+        if (generation === null) return "absent";
+        try {
+          await bucket.file(input.key, { generation }).delete();
+          return "deleted";
+        } catch (error) {
+          const code = status(error);
+          if (code === 404 || code === 412) return "absent";
+          throw error;
+        }
+      });
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  assertGcsReportingRowBucketPolicyV1,
+  createGcsReportingRowObjectProviderV1
+});

package/dist/lib/reporting/gcs/row-provider.mjs

@@ -0,0 +1,188 @@
+import { createHash } from "node:crypto";
+import { ReportingRowStoreError } from "../ledger/row-storage-errors.mjs";
+import {
+  assertReportingRowLocationKeys,
+  assertReportingRowReadBounds,
+  readReportingRowStream,
+  reportingRowClientMap,
+  reportingRowPrefixFilterOverlaps,
+  runReportingRowProviderOperation,
+  selectReportingRowClient
+} from "../ledger/row-storage-provider-io.mjs";
+const BUCKET = /^[a-z0-9][a-z0-9._-]{1,220}[a-z0-9]$/;
+const GENERATION = /^[1-9][0-9]{0,15}$/;
+const NONCURRENT_ONLY_CONDITIONS = ["numNewerVersions", "daysSinceNoncurrentTime", "noncurrentTimeBefore"];
+function status(error) {
+  if (!error || typeof error !== "object" || !("code" in error)) return void 0;
+  const code = Number(error.code);
+  return Number.isInteger(code) ? code : void 0;
+}
+function generationOf(metadata) {
+  const generation = metadata?.generation === void 0 ? "" : String(metadata.generation);
+  if (!GENERATION.test(generation) || !Number.isSafeInteger(Number(generation))) {
+    throw new ReportingRowStoreError("PROVIDER_UNAVAILABLE", "object generation is missing");
+  }
+  return generation;
+}
+function pinnedGeneration(nativeVersion) {
+  return typeof nativeVersion === "string" && GENERATION.test(nativeVersion) && Number.isSafeInteger(Number(nativeVersion)) ? nativeVersion : null;
+}
+function assertGcsReportingRowBucketPolicyV1(metadata, prefix) {
+  if (!metadata || typeof metadata !== "object") {
+    throw new ReportingRowStoreError("UNSAFE_BINDING", "bucket policy is unavailable");
+  }
+  if (metadata.iamConfiguration?.uniformBucketLevelAccess?.enabled !== true) {
+    throw new ReportingRowStoreError("UNSAFE_BINDING", "bucket must enable uniform bucket-level access");
+  }
+  if (metadata.iamConfiguration?.publicAccessPrevention !== "enforced") {
+    throw new ReportingRowStoreError("UNSAFE_BINDING", "bucket must enforce public access prevention");
+  }
+  for (const rule of metadata.lifecycle?.rule ?? []) {
+    if (rule?.action?.type !== "Delete") continue;
+    const condition = rule.condition ?? {};
+    if (condition.isLive === false) continue;
+    if (NONCURRENT_ONLY_CONDITIONS.some((name) => condition[name] !== void 0 && condition[name] !== null)) continue;
+    const prefixes = condition.matchesPrefix ?? [];
+    if (prefixes.length === 0 || prefixes.some((filter) => reportingRowPrefixFilterOverlaps(filter, prefix))) {
+      throw new ReportingRowStoreError("UNSAFE_BINDING", "a bucket lifecycle rule can delete live row objects");
+    }
+  }
+}
+function createGcsReportingRowObjectProviderV1(options) {
+  if (!options || typeof options !== "object") {
+    throw new ReportingRowStoreError("INVALID_INPUT", "GCS row provider options are required");
+  }
+  const clients = reportingRowClientMap(options.clients);
+  const isStorage = (value) => !!value && typeof value === "object" && typeof value.bucket === "function";
+  if (options.storage !== void 0 && !isStorage(options.storage) || [...clients.values()].some((client) => !isStorage(client)) || options.storage === void 0 && clients.size === 0) {
+    throw new ReportingRowStoreError("INVALID_INPUT", "inject an official Storage client as storage or clients");
+  }
+  const validateLocation = (location) => {
+    assertReportingRowLocationKeys(location, ["bucket"]);
+    if (!BUCKET.test(location.bucket) || location.bucket.includes("..")) {
+      throw new ReportingRowStoreError("INVALID_INPUT", "GCS bucket name is invalid");
+    }
+  };
+  const bucketFor = (input) => {
+    validateLocation(input.location);
+    return selectReportingRowClient(options.storage, clients, input.credentialRef).bucket(input.location.bucket);
+  };
+  const assertKey = (key) => {
+    if (typeof key !== "string" || key.length === 0 || Buffer.byteLength(key) > 1024) {
+      throw new ReportingRowStoreError("INVALID_INPUT", "object key is invalid");
+    }
+  };
+  return {
+    name: "gcs",
+    rangedReads: true,
+    validateLocation,
+    probe(input, context) {
+      return runReportingRowProviderOperation(context.signal, async () => {
+        const bucket = bucketFor(input);
+        let metadata;
+        try {
+          [metadata] = await bucket.getMetadata();
+        } catch (error) {
+          const code = status(error);
+          if (code === 404) throw new ReportingRowStoreError("UNSAFE_BINDING", "bucket does not exist");
+          if (code === 401 || code === 403) {
+            throw new ReportingRowStoreError("UNSAFE_BINDING", "bucket policy cannot be read with this client");
+          }
+          throw error;
+        }
+        assertGcsReportingRowBucketPolicyV1(metadata, input.prefix);
+      });
+    },
+    putIfAbsent(input, context) {
+      return runReportingRowProviderOperation(context.signal, async () => {
+        const bucket = bucketFor(input);
+        assertKey(input.key);
+        const file = bucket.file(input.key);
+        try {
+          const bytes = Buffer.from(input.bytes);
+          await file.save(bytes, {
+            resumable: false,
+            gzip: false,
+            // GCS verifies the declared MD5 before creating the object, so a corrupted upload
+            // is refused server-side. Client-side validation is off because on mismatch the
+            // client deletes the key without a generation precondition.
+            validation: false,
+            contentType: input.contentType,
+            metadata: {
+              contentType: input.contentType,
+              md5Hash: createHash("md5").update(bytes).digest("base64"),
+              cacheControl: "no-store",
+              metadata: { ...input.metadata }
+            },
+            preconditionOpts: { ifGenerationMatch: 0 }
+          });
+        } catch (error) {
+          if (status(error) !== 412) throw error;
+          context.signal.throwIfAborted();
+          const [existing] = await bucket.file(input.key).getMetadata();
+          return { created: false, nativeVersion: generationOf(existing) };
+        }
+        if (file.metadata?.generation !== void 0) {
+          return { created: true, nativeVersion: generationOf(file.metadata) };
+        }
+        const [created] = await file.getMetadata();
+        return { created: true, nativeVersion: generationOf(created) };
+      });
+    },
+    get(input, context) {
+      return runReportingRowProviderOperation(context.signal, async () => {
+        const bucket = bucketFor(input);
+        assertKey(input.key);
+        assertReportingRowReadBounds(input);
+        const generation = pinnedGeneration(input.nativeVersion);
+        if (generation === null) return null;
+        const file = bucket.file(input.key, { generation });
+        try {
+          if (input.range?.length === 0) {
+            const [metadata] = await file.getMetadata();
+            if (input.range.offset > Number(metadata.size)) {
+              throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "requested range exceeds the stored object");
+            }
+            return Buffer.alloc(0);
+          }
+          const stream = file.createReadStream({
+            // The client always sends `Accept-Encoding: gzip`; with `decompress: false`
+            // neither GCS nor the client transcodes, so these are the stored bytes.
+            decompress: false,
+            // Digests recorded in PostgreSQL verify every byte returned.
+            validation: false,
+            ...input.range ? { start: input.range.offset, end: input.range.offset + input.range.length - 1 } : {}
+          });
+          return await readReportingRowStream(stream, input.maxBytes, context.signal);
+        } catch (error) {
+          const code = status(error);
+          if (code === 404) return null;
+          if (code === 416) {
+            throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "requested range exceeds the stored object");
+          }
+          throw error;
+        }
+      });
+    },
+    delete(input, context) {
+      return runReportingRowProviderOperation(context.signal, async () => {
+        const bucket = bucketFor(input);
+        assertKey(input.key);
+        const generation = pinnedGeneration(input.nativeVersion);
+        if (generation === null) return "absent";
+        try {
+          await bucket.file(input.key, { generation }).delete();
+          return "deleted";
+        } catch (error) {
+          const code = status(error);
+          if (code === 404 || code === 412) return "absent";
+          throw error;
+        }
+      });
+    }
+  };
+}
+export {
+  assertGcsReportingRowBucketPolicyV1,
+  createGcsReportingRowObjectProviderV1
+};

package/dist/lib/reporting/ledger/change-feed.d.mts

@@ -0,0 +1,41 @@
+/**
+ * Host-facing reporting change feed (shared SDK persistence spec,
+ * adcontextprotocol/adcp#7996 §2.1 and §3.7).
+ *
+ * Apply after {@link REPORTING_LEDGER_MIGRATION}; PostgreSQL 13 or later
+ * (`xid8`). The store appends one row per committed obligation, revision,
+ * adjustment and retirement in the same transaction as the record, taking the
+ * sequence value only after the account lock, so per-account sequence order is
+ * commit order. Deployment-wide readers order by `(xid, seq)` and stop below
+ * the reading snapshot's `xmin`, so a slow commit is never skipped.
+ */
+export declare const REPORTING_LEDGER_CHANGES_MIGRATION: string;
+export type ReportingChangeKindV1 = 'obligation' | 'revision' | 'adjustment' | 'retirement';
+export interface ReportingChangeRecordV1 {
+    kind: ReportingChangeKindV1;
+    record_id: string;
+    reporting_obligation_id: string;
+    account_id: string;
+    recorded_at: string;
+}
+export interface ReportingChangesPageV1 {
+    records: ReportingChangeRecordV1[];
+    /** Pass back to resume. Always present; equal to the input when nothing new committed. */
+    cursor: string;
+}
+interface ChangeCursorV1 {
+    v: 1;
+    /** Account scope, or `null` for the deployment-wide feed. */
+    account: string | null;
+    seq: string;
+    /** Deployment-wide feeds only: the writing transaction of the last record returned. */
+    xid?: string;
+}
+export declare function encodeReportingChangeCursorV1(cursor: ChangeCursorV1): string;
+export declare function decodeReportingChangeCursorV1(value: string, account: string | null): ChangeCursorV1;
+/** Thrown when a change cursor is older than the retained change history. */
+export declare class ReportingChangeCursorExpiredError extends Error {
+    readonly code: "CURSOR_EXPIRED";
+    constructor();
+}
+export {};

package/dist/lib/reporting/ledger/change-feed.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Host-facing reporting change feed (shared SDK persistence spec,
+ * adcontextprotocol/adcp#7996 §2.1 and §3.7).
+ *
+ * Apply after {@link REPORTING_LEDGER_MIGRATION}; PostgreSQL 13 or later
+ * (`xid8`). The store appends one row per committed obligation, revision,
+ * adjustment and retirement in the same transaction as the record, taking the
+ * sequence value only after the account lock, so per-account sequence order is
+ * commit order. Deployment-wide readers order by `(xid, seq)` and stop below
+ * the reading snapshot's `xmin`, so a slow commit is never skipped.
+ */
+export declare const REPORTING_LEDGER_CHANGES_MIGRATION: string;
+export type ReportingChangeKindV1 = 'obligation' | 'revision' | 'adjustment' | 'retirement';
+export interface ReportingChangeRecordV1 {
+    kind: ReportingChangeKindV1;
+    record_id: string;
+    reporting_obligation_id: string;
+    account_id: string;
+    recorded_at: string;
+}
+export interface ReportingChangesPageV1 {
+    records: ReportingChangeRecordV1[];
+    /** Pass back to resume. Always present; equal to the input when nothing new committed. */
+    cursor: string;
+}
+interface ChangeCursorV1 {
+    v: 1;
+    /** Account scope, or `null` for the deployment-wide feed. */
+    account: string | null;
+    seq: string;
+    /** Deployment-wide feeds only: the writing transaction of the last record returned. */
+    xid?: string;
+}
+export declare function encodeReportingChangeCursorV1(cursor: ChangeCursorV1): string;
+export declare function decodeReportingChangeCursorV1(value: string, account: string | null): ChangeCursorV1;
+/** Thrown when a change cursor is older than the retained change history. */
+export declare class ReportingChangeCursorExpiredError extends Error {
+    readonly code: "CURSOR_EXPIRED";
+    constructor();
+}
+export {};

package/dist/lib/reporting/ledger/change-feed.js

@@ -0,0 +1,101 @@
+"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 change_feed_exports = {};
+__export(change_feed_exports, {
+  REPORTING_LEDGER_CHANGES_MIGRATION: () => REPORTING_LEDGER_CHANGES_MIGRATION,
+  ReportingChangeCursorExpiredError: () => ReportingChangeCursorExpiredError,
+  decodeReportingChangeCursorV1: () => decodeReportingChangeCursorV1,
+  encodeReportingChangeCursorV1: () => encodeReportingChangeCursorV1
+});
+module.exports = __toCommonJS(change_feed_exports);
+var import_row_storage_errors = require('./row-storage-errors.js');
+const REPORTING_LEDGER_CHANGES_MIGRATION = `
+CREATE TABLE IF NOT EXISTS adcp_reporting_changes (
+  seq BIGSERIAL PRIMARY KEY,
+  xid xid8 NOT NULL DEFAULT pg_current_xact_id(),
+  account_id TEXT NOT NULL,
+  record_kind TEXT NOT NULL
+    CHECK (record_kind IN ('obligation', 'revision', 'adjustment', 'retirement')),
+  record_id TEXT NOT NULL,
+  obligation_id TEXT NOT NULL,
+  recorded_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp()
+);
+CREATE INDEX IF NOT EXISTS adcp_reporting_changes_account
+  ON adcp_reporting_changes (account_id, seq);
+CREATE INDEX IF NOT EXISTS adcp_reporting_changes_deployment
+  ON adcp_reporting_changes (xid, seq);
+CREATE INDEX IF NOT EXISTS adcp_reporting_changes_recorded
+  ON adcp_reporting_changes (recorded_at, seq);
+
+-- Highest (xid, seq) ever pruned: a deployment-wide cursor below it may have
+-- missed a deleted change and fails closed.
+CREATE TABLE IF NOT EXISTS adcp_reporting_change_horizon (
+  singleton BOOLEAN PRIMARY KEY DEFAULT TRUE CHECK (singleton),
+  pruned_through_xid xid8 NOT NULL DEFAULT '0',
+  pruned_through_seq BIGINT NOT NULL DEFAULT 0
+);
+INSERT INTO adcp_reporting_change_horizon (singleton) VALUES (TRUE) ON CONFLICT DO NOTHING;
+
+-- Highest seq ever pruned per account: an account cursor below it fails closed.
+CREATE TABLE IF NOT EXISTS adcp_reporting_change_account_horizon (
+  account_id TEXT PRIMARY KEY,
+  pruned_through_seq BIGINT NOT NULL
+);
+
+-- Registered consumers hold back pruning in their own feed order: account
+-- consumers by seq within their account, deployment consumers by (xid, seq).
+CREATE TABLE IF NOT EXISTS adcp_reporting_feed_consumers (
+  consumer_name TEXT PRIMARY KEY CHECK (consumer_name ~ '^[A-Za-z0-9_.:-]{1,128}$'),
+  account_id TEXT,
+  cursor_xid xid8,
+  cursor_seq BIGINT NOT NULL,
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
+  CHECK ((account_id IS NULL) = (cursor_xid IS NOT NULL))
+);
+`.trim();
+function encodeReportingChangeCursorV1(cursor) {
+  return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+}
+function decodeReportingChangeCursorV1(value, account) {
+  let parsed;
+  try {
+    parsed = JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+  } catch {
+    throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "change cursor is malformed");
+  }
+  const cursor = parsed;
+  if (cursor.v !== 1 || (cursor.account ?? null) !== account || typeof cursor.seq !== "string" || !/^\d{1,19}$/.test(cursor.seq) || (account === null ? typeof cursor.xid !== "string" || !/^\d{1,20}$/.test(cursor.xid) : cursor.xid !== void 0)) {
+    throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "change cursor does not belong to this feed");
+  }
+  return cursor;
+}
+class ReportingChangeCursorExpiredError extends Error {
+  code = "CURSOR_EXPIRED";
+  constructor() {
+    super("Reporting change cursor is older than the retained change history; resynchronize from current revisions");
+    this.name = "ReportingChangeCursorExpiredError";
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  REPORTING_LEDGER_CHANGES_MIGRATION,
+  ReportingChangeCursorExpiredError,
+  decodeReportingChangeCursorV1,
+  encodeReportingChangeCursorV1
+});

package/dist/lib/reporting/ledger/change-feed.mjs

@@ -0,0 +1,74 @@
+import { ReportingRowStoreError } from "./row-storage-errors.mjs";
+const REPORTING_LEDGER_CHANGES_MIGRATION = `
+CREATE TABLE IF NOT EXISTS adcp_reporting_changes (
+  seq BIGSERIAL PRIMARY KEY,
+  xid xid8 NOT NULL DEFAULT pg_current_xact_id(),
+  account_id TEXT NOT NULL,
+  record_kind TEXT NOT NULL
+    CHECK (record_kind IN ('obligation', 'revision', 'adjustment', 'retirement')),
+  record_id TEXT NOT NULL,
+  obligation_id TEXT NOT NULL,
+  recorded_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp()
+);
+CREATE INDEX IF NOT EXISTS adcp_reporting_changes_account
+  ON adcp_reporting_changes (account_id, seq);
+CREATE INDEX IF NOT EXISTS adcp_reporting_changes_deployment
+  ON adcp_reporting_changes (xid, seq);
+CREATE INDEX IF NOT EXISTS adcp_reporting_changes_recorded
+  ON adcp_reporting_changes (recorded_at, seq);
+
+-- Highest (xid, seq) ever pruned: a deployment-wide cursor below it may have
+-- missed a deleted change and fails closed.
+CREATE TABLE IF NOT EXISTS adcp_reporting_change_horizon (
+  singleton BOOLEAN PRIMARY KEY DEFAULT TRUE CHECK (singleton),
+  pruned_through_xid xid8 NOT NULL DEFAULT '0',
+  pruned_through_seq BIGINT NOT NULL DEFAULT 0
+);
+INSERT INTO adcp_reporting_change_horizon (singleton) VALUES (TRUE) ON CONFLICT DO NOTHING;
+
+-- Highest seq ever pruned per account: an account cursor below it fails closed.
+CREATE TABLE IF NOT EXISTS adcp_reporting_change_account_horizon (
+  account_id TEXT PRIMARY KEY,
+  pruned_through_seq BIGINT NOT NULL
+);
+
+-- Registered consumers hold back pruning in their own feed order: account
+-- consumers by seq within their account, deployment consumers by (xid, seq).
+CREATE TABLE IF NOT EXISTS adcp_reporting_feed_consumers (
+  consumer_name TEXT PRIMARY KEY CHECK (consumer_name ~ '^[A-Za-z0-9_.:-]{1,128}$'),
+  account_id TEXT,
+  cursor_xid xid8,
+  cursor_seq BIGINT NOT NULL,
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
+  CHECK ((account_id IS NULL) = (cursor_xid IS NOT NULL))
+);
+`.trim();
+function encodeReportingChangeCursorV1(cursor) {
+  return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+}
+function decodeReportingChangeCursorV1(value, account) {
+  let parsed;
+  try {
+    parsed = JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+  } catch {
+    throw new ReportingRowStoreError("INVALID_INPUT", "change cursor is malformed");
+  }
+  const cursor = parsed;
+  if (cursor.v !== 1 || (cursor.account ?? null) !== account || typeof cursor.seq !== "string" || !/^\d{1,19}$/.test(cursor.seq) || (account === null ? typeof cursor.xid !== "string" || !/^\d{1,20}$/.test(cursor.xid) : cursor.xid !== void 0)) {
+    throw new ReportingRowStoreError("INVALID_INPUT", "change cursor does not belong to this feed");
+  }
+  return cursor;
+}
+class ReportingChangeCursorExpiredError extends Error {
+  code = "CURSOR_EXPIRED";
+  constructor() {
+    super("Reporting change cursor is older than the retained change history; resynchronize from current revisions");
+    this.name = "ReportingChangeCursorExpiredError";
+  }
+}
+export {
+  REPORTING_LEDGER_CHANGES_MIGRATION,
+  ReportingChangeCursorExpiredError,
+  decodeReportingChangeCursorV1,
+  encodeReportingChangeCursorV1
+};

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

@@ -15,6 +15,12 @@ export interface ReportingStatusConsumerScopeOptionsV1<TContext = unknown> {
 }
 export declare function createReportingStatusHandler(store: ReportingLedgerStore): (request: Parameters<ReportingStatusHandlerV1>[0], context: Pick<Parameters<ReportingStatusHandlerV1>[1], 'account' | 'signal'>) => ReturnType<ReportingStatusHandlerV1>;
 export declare function createReportingStatusHandler<TContext = unknown>(store: ReportingLedgerStore, options?: ReportingStatusConsumerScopeOptionsV1<TContext>): ReportingStatusHandlerV1;
+/**
+ * Largest revision whose rows the `get_reporting_status` `revision` view
+ * returns inline. Larger revisions omit `reporting_rows` there; callers page
+ * them through the exact `get_media_buy_delivery` read.
+ */
+export declare const REPORTING_STATUS_REVISION_VIEW_MAX_ROWS = 10000;
 /** Exact revision reader for createAdcpServer's getMediaBuyDelivery slot. */
 export declare function createReportingDeliveryHandler(store: ReportingLedgerStore): ReportingDeliveryHandlerV1;
 export interface ProjectManagedDeliveryInputV1 {