@adcp/sdk 15.4.0 → 15.5.0

package/dist/lib/reporting/ledger/row-storage.mjs

@@ -0,0 +1,680 @@
+import { createHash, randomUUID } from "crypto";
+import { gunzipSync, gzipSync } from "zlib";
+import { canonicalize } from "../../utils/jcs.mjs";
+import {
+  REPORTING_ROW_CHUNK_MAX_BYTES,
+  REPORTING_ROW_ENCODING_V1,
+  createReportingRevisionEnvelopeHasherV1,
+  createReportingRowsOnlyHasherV1,
+  decodeVerifiedReportingRowSegmentsV1,
+  encodeReportingRowsV1,
+  isReportingRowEncodingError,
+  verifyReportingRowChunkV1,
+  verifyReportingRowManifestsV1
+} from "./row-encoding.mjs";
+import { probeReportingRowStorageSchemaV1 } from "./row-storage-migration.mjs";
+import { ReportingRowStoreError, isReportingRowStoreError } from "./row-storage-errors.mjs";
+import {
+  REPORTING_ROW_DEFAULT_KEY_TEMPLATE,
+  assertReportingRowKeyTemplateV1,
+  assertReportingRowPrefixV1,
+  renderReportingRowObjectKeyV1
+} from "./row-storage-object.mjs";
+import { ReportingRowStoreError as ReportingRowStoreError2, isReportingRowStoreError as isReportingRowStoreError2 } from "./row-storage-errors.mjs";
+const DEFAULT_BINDING_ID = "postgres";
+const BINDING_ID = /^[A-Za-z0-9_.:-]{1,128}$/;
+const CREDENTIAL_REF = /^[A-Za-z0-9_.:-]{1,128}$/;
+const MAX_ADOPTED_OBJECT_BYTES = 2 * REPORTING_ROW_CHUNK_MAX_BYTES + 1024 * 1024;
+class ReportingRowStorageV1 {
+  constructor(pool, options = {}) {
+    this.pool = pool;
+    this.options = options;
+    const bindings = options.bindings ?? { [DEFAULT_BINDING_ID]: { kind: "postgres" } };
+    this.providers = Object.freeze({ ...options.providers ?? {} });
+    const ids = Object.keys(bindings);
+    if (ids.length === 0) throw new ReportingRowStoreError("INVALID_INPUT", "at least one row binding is required");
+    for (const id of ids) {
+      if (!BINDING_ID.test(id)) throw new ReportingRowStoreError("INVALID_INPUT", `invalid row binding ID ${id}`);
+      const binding = bindings[id];
+      if (binding.kind === "postgres") continue;
+      if (binding.kind !== "object") {
+        throw new ReportingRowStoreError("INVALID_INPUT", `row binding ${id} has an unsupported kind`);
+      }
+      const provider = this.providers[binding.provider];
+      if (!provider) throw new ReportingRowStoreError("INVALID_INPUT", `row binding ${id} names an unknown provider`);
+      provider.validateLocation(binding.location);
+      assertReportingRowPrefixV1(binding.prefix);
+      assertReportingRowKeyTemplateV1(binding.keyTemplate ?? REPORTING_ROW_DEFAULT_KEY_TEMPLATE);
+      if (binding.credentialRef !== void 0 && !CREDENTIAL_REF.test(binding.credentialRef)) {
+        throw new ReportingRowStoreError("INVALID_INPUT", `row binding ${id} has an invalid credentialRef`);
+      }
+    }
+    this.bindings = Object.freeze({ ...bindings });
+    this.deploymentNamespace = options.deploymentNamespace ?? "default";
+    if (!this.deploymentNamespace || this.deploymentNamespace.length > 256) {
+      throw new ReportingRowStoreError("INVALID_INPUT", "deploymentNamespace must be 1-256 characters");
+    }
+    this.writeDeadline = positiveMilliseconds(options.writeDeadlineMilliseconds ?? 6e4, "writeDeadlineMilliseconds");
+    this.readDeadline = positiveMilliseconds(options.readDeadlineMilliseconds ?? 3e4, "readDeadlineMilliseconds");
+  }
+  pool;
+  options;
+  bindings;
+  providers;
+  deploymentNamespace;
+  writeDeadline;
+  readDeadline;
+  readied;
+  installation;
+  /** Deadline budget a writer must still hold on its lease before uploading. */
+  get writeDeadlineMilliseconds() {
+    return this.writeDeadline;
+  }
+  /** Probe the schema and every provider, and register (or verify) every configured binding. Idempotent. */
+  ready() {
+    this.readied ??= this.register().catch((error) => {
+      this.readied = void 0;
+      throw error;
+    });
+    return this.readied;
+  }
+  /** Encode rows, prove the chunks reproduce the committed binding, select a binding and plan objects. */
+  async prepare(input) {
+    await this.ready();
+    let encoded;
+    try {
+      encoded = encodeReportingRowsV1(input.rows);
+    } catch (error) {
+      if (isReportingRowEncodingError(error)) throw new ReportingRowStoreError("INVALID_INPUT", error.message);
+      throw error;
+    }
+    const digestProfile = input.rowSetKind === "revision" ? "revision_envelope_v1" : "rows_v1";
+    const hasher = digestProfile === "revision_envelope_v1" ? createReportingRevisionEnvelopeHasherV1({
+      reporting_revision_id: input.rowSetId,
+      row_count: input.rows.length,
+      control_totals: input.controlTotals ?? []
+    }) : createReportingRowsOnlyHasherV1(input.rows.length);
+    for (const chunk of encoded.chunks) hasher.update(chunk.bytes);
+    const digest = hasher.digest();
+    if (digest.sha256 !== input.binding.sha256 || digest.byteCount !== input.binding.byteCount || input.binding.rowCount !== input.rows.length) {
+      throw new ReportingRowStoreError("INVALID_INPUT", "rows do not reproduce their committed binding");
+    }
+    const ids = Object.keys(this.bindings);
+    const bindingId = input.bindingId ? input.bindingId : this.options.selectRowBinding ? await this.options.selectRowBinding({
+      account_id: input.accountId,
+      reporting_obligation_id: input.obligationId,
+      row_set_kind: input.rowSetKind,
+      ...input.finality ? { finality: input.finality } : {},
+      row_count: input.rows.length,
+      canonical_byte_count: digest.byteCount
+    }) : ids.length === 1 ? ids[0] : DEFAULT_BINDING_ID;
+    const binding = this.bindings[bindingId];
+    if (!binding) throw new ReportingRowStoreError("STATE_UNAVAILABLE", `row binding ${bindingId} is not configured`);
+    if (binding.kind === "postgres") return Object.freeze({ input, encoded, bindingId, binding, digestProfile });
+    const compression = binding.compression ?? "gzip";
+    const namespaceKey = this.installation.namespaceKey;
+    const objects = encoded.chunks.map((chunk) => {
+      const physicalBytes = compression === "gzip" ? gzipSync(chunk.bytes, { level: 6 }) : chunk.bytes;
+      return Object.freeze({
+        key: renderReportingRowObjectKeyV1({
+          template: binding.keyTemplate ?? REPORTING_ROW_DEFAULT_KEY_TEMPLATE,
+          prefix: binding.prefix,
+          namespaceKey,
+          accountId: input.accountId,
+          rowSetId: input.rowSetId,
+          ...input.periodStart ? { periodStart: input.periodStart } : {},
+          ...input.finality ? { finality: input.finality } : {},
+          contentSha256: input.binding.sha256,
+          chunkIndex: chunk.manifest.chunk_index,
+          compression
+        }),
+        physicalBytes,
+        physicalSha256: sha256Hex(physicalBytes),
+        compression
+      });
+    });
+    return Object.freeze({ input, encoded, bindingId, binding, digestProfile, objects: Object.freeze(objects) });
+  }
+  /**
+   * Upload a prepared object-kind row set, create-only. An object already at a
+   * planned key is adopted only when its bytes decode to the exact chunk;
+   * otherwise `CONTENT_CONFLICT`. `onCreated` is awaited for every object this
+   * call created, before the next upload, so the caller can record it in its
+   * write intent.
+   */
+  async upload(prepared, intentId, onCreated, signal) {
+    const binding = prepared.binding;
+    if (binding.kind !== "object" || !prepared.objects) {
+      throw new ReportingRowStoreError("INVALID_INPUT", "only object-kind row sets are uploaded");
+    }
+    const provider = this.providers[binding.provider];
+    const context = { signal: deadlineSignal(this.writeDeadline, signal) };
+    const location = providerLocation(binding);
+    const locators = [];
+    for (const [index, object] of prepared.objects.entries()) {
+      const manifest = prepared.encoded.manifests[index];
+      const put = await this.provider(
+        () => provider.putIfAbsent(
+          {
+            ...location,
+            key: object.key,
+            bytes: object.physicalBytes,
+            contentType: object.compression === "gzip" ? "application/gzip" : "application/x-ndjson",
+            metadata: {
+              "adcp-installation": this.installation.installationId,
+              "adcp-intent": intentId
+            }
+          },
+          context
+        )
+      );
+      if (put.created) {
+        await onCreated({ objectKey: object.key, nativeVersion: put.nativeVersion });
+        locators.push({
+          objectKey: object.key,
+          nativeVersion: put.nativeVersion,
+          compression: object.compression,
+          physicalSha256: object.physicalSha256,
+          physicalByteCount: object.physicalBytes.byteLength,
+          created: true
+        });
+        continue;
+      }
+      const existing = await this.provider(
+        () => provider.get(
+          { ...location, key: object.key, nativeVersion: put.nativeVersion, maxBytes: MAX_ADOPTED_OBJECT_BYTES },
+          context
+        )
+      );
+      const logical = existing ? this.inflate(Buffer.from(existing), object.compression, manifest.byte_count) : null;
+      if (!existing || !logical || sha256Hex(logical) !== manifest.sha256) {
+        throw new ReportingRowStoreError("CONTENT_CONFLICT", `object for chunk ${index} holds different bytes`);
+      }
+      locators.push({
+        objectKey: object.key,
+        nativeVersion: put.nativeVersion,
+        compression: object.compression,
+        physicalSha256: sha256Hex(existing),
+        physicalByteCount: existing.byteLength,
+        created: false
+      });
+    }
+    return locators;
+  }
+  /**
+   * Persist a prepared row set inside the caller's ledger transaction:
+   * bodies for the `postgres` kind, or the uploaded locators for the object
+   * kind. Replays of an identical row set are no-ops; a conflicting row set
+   * under the same ID is refused.
+   */
+  async writeInTransaction(transaction, prepared, locators, sharedFromRowSetId) {
+    const { input, encoded } = prepared;
+    if (prepared.binding.kind === "object" && locators?.length !== encoded.chunks.length) {
+      throw new ReportingRowStoreError("INVALID_INPUT", "object-kind row sets need one locator per chunk");
+    }
+    const inserted = await transaction.query(
+      `INSERT INTO adcp_reporting_row_sets
+         (row_set_id, row_set_kind, account_id, obligation_id, encoding, digest_profile, content_sha256,
+          canonical_byte_count, row_count, row_manifest_sha256, chunk_count, row_binding_id,
+          rows_shared_from_row_set_id)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)
+       ON CONFLICT (row_set_id) DO NOTHING`,
+      [
+        input.rowSetId,
+        input.rowSetKind,
+        input.accountId,
+        input.obligationId,
+        REPORTING_ROW_ENCODING_V1,
+        prepared.digestProfile,
+        input.binding.sha256,
+        input.binding.byteCount,
+        encoded.rowCount,
+        encoded.rowManifestSha256,
+        encoded.chunks.length,
+        prepared.bindingId,
+        sharedFromRowSetId ?? null
+      ]
+    );
+    if (inserted.rowCount !== 1) {
+      const existing = await transaction.query(
+        "SELECT content_sha256, row_manifest_sha256 FROM adcp_reporting_row_sets WHERE row_set_id = $1",
+        [input.rowSetId]
+      );
+      const row = existing.rows[0];
+      if (!row || row.content_sha256 !== input.binding.sha256 || row.row_manifest_sha256 !== encoded.rowManifestSha256) {
+        throw new ReportingRowStoreError("CONTENT_CONFLICT", "row set identity names different content");
+      }
+      return;
+    }
+    for (const [index, chunk] of encoded.chunks.entries()) {
+      const manifest = chunk.manifest;
+      const locator = locators?.[index];
+      if (!locator) {
+        await transaction.query(
+          `INSERT INTO adcp_reporting_chunk_bodies (account_id, obligation_id, sha256, body)
+           VALUES ($1, $2, $3, $4) ON CONFLICT DO NOTHING`,
+          [input.accountId, input.obligationId, manifest.sha256, chunk.bytes]
+        );
+      }
+      await transaction.query(
+        `INSERT INTO adcp_reporting_row_chunks
+           (row_set_id, chunk_index, account_id, obligation_id, first_ordinal, row_count, byte_count, sha256, segments,
+            object_key, native_version, compression, physical_sha256, physical_byte_count)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9::jsonb, $10, $11, $12, $13, $14)`,
+        [
+          input.rowSetId,
+          manifest.chunk_index,
+          input.accountId,
+          input.obligationId,
+          manifest.first_ordinal,
+          manifest.row_count,
+          manifest.byte_count,
+          manifest.sha256,
+          JSON.stringify(manifest.segments),
+          locator?.objectKey ?? null,
+          locator?.nativeVersion ?? null,
+          locator?.compression ?? "none",
+          locator?.physicalSha256 ?? null,
+          locator?.physicalByteCount ?? null
+        ]
+      );
+    }
+  }
+  /**
+   * Load a row set and verify its chunk manifest against the committed digest.
+   * Returns `null` when no row set exists (legacy inline rows) or it belongs
+   * to another account. Throws `ROWS_EXPIRED` / `ROWS_UNAVAILABLE` when the
+   * rows were pruned or lost.
+   */
+  async find(rowSetId, accountId, queryable = this.pool) {
+    const found = await queryable.query(
+      `SELECT row_set.row_set_id, row_set.row_set_kind, row_set.account_id, row_set.obligation_id,
+              row_set.digest_profile, row_set.content_sha256, row_set.canonical_byte_count, row_set.row_count,
+              row_set.row_manifest_sha256, row_set.chunk_count, row_set.row_binding_id,
+              row_set.row_location_version, row_set.rows_state, binding.kind, binding.identity_sha256
+         FROM adcp_reporting_row_sets row_set
+         JOIN adcp_reporting_row_bindings binding ON binding.row_binding_id = row_set.row_binding_id
+        WHERE row_set.row_set_id = $1 AND row_set.account_id = $2`,
+      [rowSetId, accountId]
+    );
+    const record = found.rows[0];
+    if (!record) return null;
+    if (record.rows_state === "pruning" || record.rows_state === "pruned") {
+      throw new ReportingRowStoreError("ROWS_EXPIRED");
+    }
+    if (record.rows_state === "unavailable") throw new ReportingRowStoreError("ROWS_UNAVAILABLE");
+    const chunks = await queryable.query(
+      `SELECT chunk_index, first_ordinal, row_count, byte_count, sha256, segments,
+              object_key, native_version, compression, physical_sha256, physical_byte_count
+         FROM adcp_reporting_row_chunks WHERE row_set_id = $1 ORDER BY chunk_index`,
+      [rowSetId]
+    );
+    const manifests = chunks.rows.map((chunk) => ({
+      chunk_index: chunk.chunk_index,
+      first_ordinal: Number(chunk.first_ordinal),
+      row_count: chunk.row_count,
+      byte_count: Number(chunk.byte_count),
+      sha256: chunk.sha256,
+      segments: chunk.segments.map((segment) => ({
+        first_ordinal: Number(segment.first_ordinal),
+        row_count: Number(segment.row_count),
+        byte_offset: Number(segment.byte_offset),
+        byte_count: Number(segment.byte_count),
+        sha256: segment.sha256
+      }))
+    }));
+    const rowCount = Number(record.row_count);
+    try {
+      verifyReportingRowManifestsV1(manifests, { rowCount, rowManifestSha256: record.row_manifest_sha256 });
+    } catch (error) {
+      if (isReportingRowEncodingError(error)) throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", error.message);
+      throw error;
+    }
+    if (manifests.length !== record.chunk_count) {
+      throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "chunk count does not match the row set");
+    }
+    const locators = chunks.rows.map((chunk) => {
+      const hasLocation = chunk.object_key !== null;
+      if (hasLocation !== (record.kind === "object")) {
+        throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "chunk location does not match its binding kind");
+      }
+      return hasLocation ? Object.freeze({
+        objectKey: chunk.object_key,
+        nativeVersion: chunk.native_version,
+        compression: chunk.compression,
+        physicalSha256: chunk.physical_sha256,
+        physicalByteCount: Number(chunk.physical_byte_count)
+      }) : void 0;
+    });
+    return Object.freeze({
+      rowSetId: record.row_set_id,
+      rowSetKind: record.row_set_kind,
+      accountId: record.account_id,
+      obligationId: record.obligation_id,
+      digestProfile: record.digest_profile,
+      contentSha256: record.content_sha256,
+      canonicalByteCount: Number(record.canonical_byte_count),
+      rowCount,
+      rowManifestSha256: record.row_manifest_sha256,
+      bindingId: record.row_binding_id,
+      bindingIdentitySha256: record.identity_sha256,
+      kind: record.kind,
+      manifests: Object.freeze(manifests),
+      locators: Object.freeze(locators)
+    });
+  }
+  /** Verified rows `[offset, offset + limit)` in ordinal order. */
+  async readPage(handle, offset, limit, signal) {
+    if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(limit) || limit < 1) {
+      throw new ReportingRowStoreError("INVALID_INPUT", "row page bounds are invalid");
+    }
+    const end = Math.min(handle.rowCount, offset + limit);
+    const rows = [];
+    for (const manifest of handle.manifests) {
+      if (offset >= end) break;
+      const chunkEnd = manifest.first_ordinal + manifest.row_count;
+      if (chunkEnd <= offset || manifest.first_ordinal >= end) continue;
+      signal?.throwIfAborted();
+      const from = manifest.segments.findIndex(
+        (segment) => segment.first_ordinal + segment.row_count > Math.max(offset, manifest.first_ordinal)
+      );
+      let to = from;
+      while (to + 1 < manifest.segments.length && manifest.segments[to + 1].first_ordinal < end) to += 1;
+      const firstSegment = manifest.segments[from];
+      const lastSegment = manifest.segments[to];
+      const bytes = await this.readChunkRange(
+        handle,
+        manifest,
+        firstSegment.byte_offset,
+        lastSegment.byte_offset + lastSegment.byte_count - firstSegment.byte_offset,
+        signal
+      );
+      const decoded = this.decode(() => decodeVerifiedReportingRowSegmentsV1(manifest, [from, to], bytes));
+      const startIndex = Math.max(offset, firstSegment.first_ordinal) - firstSegment.first_ordinal;
+      const endIndex = Math.min(end, lastSegment.first_ordinal + lastSegment.row_count) - firstSegment.first_ordinal;
+      rows.push(...decoded.slice(startIndex, endIndex));
+    }
+    return rows;
+  }
+  /**
+   * Every row, verified chunk by chunk and against the committed binding.
+   * `controlTotals` are required for revision row sets.
+   */
+  async readAll(handle, controlTotals, options = {}) {
+    if (options.maxBytes !== void 0 && handle.canonicalByteCount > options.maxBytes) {
+      throw new ReportingRowStoreError("INVALID_INPUT", "row set exceeds the hydration byte limit");
+    }
+    const hasher = handle.digestProfile === "revision_envelope_v1" ? createReportingRevisionEnvelopeHasherV1({
+      reporting_revision_id: handle.rowSetId,
+      row_count: handle.rowCount,
+      control_totals: controlTotals ?? []
+    }) : createReportingRowsOnlyHasherV1(handle.rowCount);
+    const rows = [];
+    for (const manifest of handle.manifests) {
+      options.signal?.throwIfAborted();
+      const bytes = await this.readChunkRange(handle, manifest, 0, manifest.byte_count, options.signal);
+      this.decode(() => verifyReportingRowChunkV1(manifest, bytes));
+      hasher.update(bytes);
+      rows.push(
+        ...this.decode(() => decodeVerifiedReportingRowSegmentsV1(manifest, [0, manifest.segments.length - 1], bytes))
+      );
+    }
+    const digest = this.decode(() => hasher.digest());
+    if (digest.sha256 !== handle.contentSha256 || digest.byteCount !== handle.canonicalByteCount) {
+      throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "rows do not reproduce the committed binding");
+    }
+    return rows;
+  }
+  /**
+   * Delete exact object versions through the configured binding's provider.
+   * `absent` counts as success. Only object-kind bindings are accepted.
+   */
+  async deleteObjects(bindingId, objects, signal) {
+    await this.ready();
+    const binding = this.bindings[bindingId];
+    if (!binding || binding.kind !== "object") {
+      throw new ReportingRowStoreError("STATE_UNAVAILABLE", `row binding ${bindingId} is not configured for objects`);
+    }
+    const provider = this.providers[binding.provider];
+    const ownedPrefix = `${binding.prefix}/${this.installation.namespaceKey}/`;
+    const context = { signal: deadlineSignal(this.writeDeadline, signal) };
+    for (const object of objects) {
+      if (!object.objectKey.startsWith(ownedPrefix)) {
+        throw new ReportingRowStoreError("UNSAFE_BINDING", "refusing to delete an object outside the owned prefix");
+      }
+      await this.provider(
+        () => provider.delete(
+          { ...providerLocation(binding), key: object.objectKey, nativeVersion: object.nativeVersion },
+          context
+        )
+      );
+    }
+  }
+  /**
+   * A live row set in the same obligation and binding whose rows are
+   * byte-identical (same manifest digest), with its chunk locations. Sharing
+   * never crosses obligations, so it never crosses consumers.
+   */
+  async findShareable(queryable, prepared) {
+    if (prepared.encoded.chunks.length === 0) return void 0;
+    const found = await queryable.query(
+      `SELECT row_set_id FROM adcp_reporting_row_sets
+        WHERE obligation_id = $1 AND account_id = $2 AND row_binding_id = $3 AND row_manifest_sha256 = $4
+          AND rows_state = 'live' AND row_set_id <> $5
+        ORDER BY recorded_at DESC, row_set_id LIMIT 1
+        FOR SHARE`,
+      [
+        prepared.input.obligationId,
+        prepared.input.accountId,
+        prepared.bindingId,
+        prepared.encoded.rowManifestSha256,
+        prepared.input.rowSetId
+      ]
+    );
+    const rowSetId = found.rows[0]?.row_set_id;
+    if (!rowSetId) return void 0;
+    const chunks = await queryable.query(
+      `SELECT object_key, native_version, compression, physical_sha256, physical_byte_count
+         FROM adcp_reporting_row_chunks WHERE row_set_id = $1 ORDER BY chunk_index`,
+      [rowSetId]
+    );
+    if (chunks.rows.length !== prepared.encoded.chunks.length) return void 0;
+    if (prepared.binding.kind === "postgres") return { rowSetId, locators: [] };
+    if (chunks.rows.some((chunk) => chunk.object_key === null)) return void 0;
+    return {
+      rowSetId,
+      locators: chunks.rows.map((chunk) => ({
+        objectKey: chunk.object_key,
+        nativeVersion: chunk.native_version,
+        compression: chunk.compression,
+        physicalSha256: chunk.physical_sha256,
+        physicalByteCount: Number(chunk.physical_byte_count),
+        created: false
+      }))
+    };
+  }
+  /** Installation identity and namespace key; available after `ready()`. */
+  get installationIdentity() {
+    if (!this.installation) throw new ReportingRowStoreError("STATE_UNAVAILABLE", "row storage is not ready");
+    return this.installation;
+  }
+  async readChunkRange(handle, manifest, byteOffset, byteCount, signal) {
+    if (handle.kind === "postgres") {
+      const result = await this.pool.query(
+        `SELECT substring(body FROM $4::integer + 1 FOR $5::integer) AS bytes
+           FROM adcp_reporting_chunk_bodies
+          WHERE account_id = $1 AND obligation_id = $2 AND sha256 = $3`,
+        [handle.accountId, handle.obligationId, manifest.sha256, byteOffset, byteCount]
+      );
+      const bytes = result.rows[0]?.bytes;
+      if (!bytes) throw new ReportingRowStoreError("ROWS_UNAVAILABLE", `chunk ${manifest.chunk_index} body is missing`);
+      return bytes;
+    }
+    const binding = this.bindings[handle.bindingId];
+    if (!binding || binding.kind !== "object" || bindingIdentitySha256(binding) !== handle.bindingIdentitySha256) {
+      throw new ReportingRowStoreError("STATE_UNAVAILABLE", `row binding ${handle.bindingId} is not configured`);
+    }
+    const locator = handle.locators[manifest.chunk_index];
+    const provider = this.providers[binding.provider];
+    const context = { signal: deadlineSignal(this.readDeadline, signal) };
+    const location = providerLocation(binding);
+    if (locator.compression === "none" && provider.rangedReads) {
+      const bytes = await this.provider(
+        () => provider.get(
+          {
+            ...location,
+            key: locator.objectKey,
+            nativeVersion: locator.nativeVersion,
+            range: { offset: byteOffset, length: byteCount },
+            maxBytes: byteCount
+          },
+          context
+        )
+      );
+      if (!bytes)
+        throw new ReportingRowStoreError("ROWS_UNAVAILABLE", `chunk ${manifest.chunk_index} object is missing`);
+      if (bytes.byteLength !== byteCount) {
+        throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", `chunk ${manifest.chunk_index} range is truncated`);
+      }
+      return Buffer.from(bytes);
+    }
+    const stored = await this.provider(
+      () => provider.get(
+        {
+          ...location,
+          key: locator.objectKey,
+          nativeVersion: locator.nativeVersion,
+          maxBytes: locator.physicalByteCount
+        },
+        context
+      )
+    );
+    if (!stored)
+      throw new ReportingRowStoreError("ROWS_UNAVAILABLE", `chunk ${manifest.chunk_index} object is missing`);
+    const physical = Buffer.from(stored);
+    if (physical.byteLength !== locator.physicalByteCount || sha256Hex(physical) !== locator.physicalSha256) {
+      throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", `chunk ${manifest.chunk_index} stored bytes differ`);
+    }
+    const logical = this.inflate(physical, locator.compression, manifest.byte_count);
+    if (!logical) {
+      throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", `chunk ${manifest.chunk_index} does not decompress`);
+    }
+    return logical.subarray(byteOffset, byteOffset + byteCount);
+  }
+  inflate(physical, compression, byteCount) {
+    if (compression === "none") return physical.byteLength === byteCount ? physical : null;
+    try {
+      const logical = gunzipSync(physical, { maxOutputLength: byteCount });
+      return logical.byteLength === byteCount ? logical : null;
+    } catch {
+      return null;
+    }
+  }
+  decode(operation) {
+    try {
+      return operation();
+    } catch (error) {
+      if (isReportingRowEncodingError(error)) throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", error.message);
+      throw error;
+    }
+  }
+  /** Collapse provider failures to stable, secret-free codes. */
+  async provider(operation) {
+    try {
+      return await operation();
+    } catch (error) {
+      if (isReportingRowStoreError(error)) throw error;
+      if (error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError")) {
+        throw new ReportingRowStoreError(error.name === "TimeoutError" ? "DEADLINE_EXCEEDED" : "ABORTED");
+      }
+      throw new ReportingRowStoreError("PROVIDER_UNAVAILABLE");
+    }
+  }
+  async register() {
+    const { installationId } = await probeReportingRowStorageSchemaV1(this.pool);
+    const namespaceKey = sha256Hex(canonicalize(["adcp.rows.v1", this.deploymentNamespace, installationId]));
+    this.installation = { installationId, namespaceKey };
+    for (const [bindingId, binding] of Object.entries(this.bindings)) {
+      if (binding.kind === "object") {
+        const provider = this.providers[binding.provider];
+        await this.provider(
+          () => provider.probe(
+            { ...providerLocation(binding), prefix: binding.prefix },
+            { signal: AbortSignal.timeout(this.readDeadline) }
+          )
+        );
+      }
+      const identityConfig = bindingIdentityConfig(binding);
+      const identitySha256 = bindingIdentitySha256(binding);
+      const operationalConfig = binding.kind === "object" ? {
+        compression: binding.compression ?? "gzip",
+        ...binding.credentialRef ? { credentialRef: binding.credentialRef } : {}
+      } : {};
+      await this.pool.query(
+        `INSERT INTO adcp_reporting_row_bindings
+           (row_binding_id, kind, provider, identity_config, identity_sha256, operational_config, namespace_key)
+         VALUES ($1, $2, $3, $4::jsonb, $5, $6::jsonb, $7)
+         ON CONFLICT (row_binding_id) DO NOTHING`,
+        [
+          bindingId,
+          binding.kind,
+          binding.kind === "object" ? binding.provider : "postgres",
+          JSON.stringify(identityConfig),
+          identitySha256,
+          JSON.stringify(operationalConfig),
+          namespaceKey
+        ]
+      );
+      const stored = await this.pool.query(
+        "SELECT identity_sha256, namespace_key, state FROM adcp_reporting_row_bindings WHERE row_binding_id = $1",
+        [bindingId]
+      );
+      const row = stored.rows[0];
+      if (!row || row.identity_sha256 !== identitySha256) {
+        throw new ReportingRowStoreError(
+          "UNSAFE_BINDING",
+          `row binding ${bindingId} identity differs from its definition`
+        );
+      }
+      if (row.namespace_key !== namespaceKey) {
+        throw new ReportingRowStoreError("UNSAFE_BINDING", `row binding ${bindingId} belongs to another installation`);
+      }
+    }
+  }
+}
+function bindingIdentityConfig(binding) {
+  return binding.kind === "object" ? {
+    location: { ...binding.location },
+    prefix: binding.prefix,
+    keyTemplate: binding.keyTemplate ?? REPORTING_ROW_DEFAULT_KEY_TEMPLATE
+  } : {};
+}
+function bindingIdentitySha256(binding) {
+  const provider = binding.kind === "object" ? binding.provider : binding.kind;
+  return sha256Hex(canonicalize([binding.kind, provider, bindingIdentityConfig(binding)]));
+}
+function providerLocation(binding) {
+  return { location: binding.location, ...binding.credentialRef ? { credentialRef: binding.credentialRef } : {} };
+}
+function deadlineSignal(milliseconds, signal) {
+  const timeout = AbortSignal.timeout(milliseconds);
+  return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+function positiveMilliseconds(value, name) {
+  if (!Number.isSafeInteger(value) || value < 1e3 || value > 6e5) {
+    throw new ReportingRowStoreError("INVALID_INPUT", `${name} must be between 1000 and 600000`);
+  }
+  return value;
+}
+function sha256Hex(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+function reportingRowWriteIntentIdV1() {
+  return randomUUID();
+}
+export {
+  ReportingRowStorageV1,
+  ReportingRowStoreError2 as ReportingRowStoreError,
+  isReportingRowStoreError2 as isReportingRowStoreError,
+  reportingRowWriteIntentIdV1
+};

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

@@ -756,6 +756,14 @@ export interface ReportingLedgerStore {
     }>;
     getObligation(reporting_obligation_id: string, account_id?: string): Promise<ReportingLedgerObligationV1 | null>;
     listObligations(account_id?: string): Promise<ReportingLedgerObligationV1[]>;
+    /**
+     * Optional: periods whose ledger records were retired by retention. The
+     * planner treats them as already covered so it never re-creates them.
+     */
+    listRetiredObligationOrdinals?(account_id?: string): Promise<{
+        configurationId: string;
+        periodOrdinal: number;
+    }[]>;
     listLifecycleDueObligations(input: {
         ledgerAsOf: string;
         account_id?: string;