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

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

@@ -1,812 +0,0 @@
-"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_storage_exports = {};
-__export(row_storage_exports, {
-  ReportingRowStorageV1: () => ReportingRowStorageV1,
-  ReportingRowStoreError: () => import_row_storage_errors2.ReportingRowStoreError,
-  isReportingRowStoreError: () => import_row_storage_errors2.isReportingRowStoreError,
-  reportingRowWriteIntentIdV1: () => reportingRowWriteIntentIdV1
-});
-module.exports = __toCommonJS(row_storage_exports);
-var import_crypto = require("crypto");
-var import_zlib = require("zlib");
-var import_jcs = require('../../utils/jcs.js');
-var import_row_encoding = require('./row-encoding.js');
-var import_row_storage_migration = require('./row-storage-migration.js');
-var import_row_storage_errors = require('./row-storage-errors.js');
-var import_row_storage_object = require('./row-storage-object.js');
-var import_row_storage_errors2 = require('./row-storage-errors.js');
-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 * import_row_encoding.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 import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "at least one row binding is required");
-    for (const id of ids) {
-      if (!BINDING_ID.test(id)) throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", `invalid row binding ID ${id}`);
-      const binding = bindings[id];
-      if (binding.kind === "postgres") continue;
-      if (binding.kind !== "object") {
-        throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", `row binding ${id} has an unsupported kind`);
-      }
-      const provider = this.providers[binding.provider];
-      if (!provider) throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", `row binding ${id} names an unknown provider`);
-      provider.validateLocation(binding.location);
-      (0, import_row_storage_object.assertReportingRowPrefixV1)(binding.prefix);
-      if (binding.credentialRef !== void 0 && !CREDENTIAL_REF.test(binding.credentialRef)) {
-        throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", `row binding ${id} has an invalid credentialRef`);
-      }
-    }
-    this.bindings = Object.freeze(
-      Object.fromEntries(Object.entries(bindings).map(([id, binding]) => [id, Object.freeze({ ...binding })]))
-    );
-    this.assertBindingKeyTemplates();
-    this.deploymentNamespace = options.deploymentNamespace ?? "default";
-    if (!this.deploymentNamespace || this.deploymentNamespace.length > 256) {
-      throw new import_row_storage_errors.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;
-  }
-  /** Every writable object binding's key template must include `{revision_key}`; throws `INVALID_INPUT`. */
-  assertBindingKeyTemplates() {
-    for (const [id, binding] of Object.entries(this.bindings)) {
-      if (binding.kind !== "object") continue;
-      try {
-        (0, import_row_storage_object.assertReportingRowKeyTemplateV1)(binding.keyTemplate ?? import_row_storage_object.REPORTING_ROW_DEFAULT_KEY_TEMPLATE, {
-          requireRevisionKey: binding.readOnly !== true
-        });
-      } catch (error) {
-        if ((0, import_row_storage_errors.isReportingRowStoreError)(error)) {
-          throw new import_row_storage_errors.ReportingRowStoreError(
-            "INVALID_INPUT",
-            `row binding ${id}: ${error.message.replace(/^Reporting row store: INVALID_INPUT: /, "")}`
-          );
-        }
-        throw error;
-      }
-    }
-  }
-  /**
-   * Refuse a configuration in which compaction could delete an object a concurrent commit is
-   * adopting. An object binding whose key template omits `{revision_key}` can map two revisions
-   * with identical chunk content to one object key, and a create-only write adopts an existing
-   * object with identical bytes. Compaction deleting that object at the same moment would leave
-   * the newer revision without its rows. Every writable binding is already required to include
-   * `{revision_key}`, so this cannot fail for a validated configuration. A `readOnly` binding is
-   * skipped: it never takes commits, so nothing can adopt through it, and every delete is
-   * reference-checked.
-   *
-   * Since the reference-checked, per-object-locked delete this is no longer the only guard: every
-   * delete path now skips an object another row set still references. It is kept as defense in
-   * depth for compaction, the one path that deletes content while the obligation stays live.
-   */
-  assertCompactionSafeKeyTemplates() {
-    const unsafe = Object.entries(this.bindings).filter(
-      ([, binding]) => binding.kind === "object" && binding.readOnly !== true && !(binding.keyTemplate ?? import_row_storage_object.REPORTING_ROW_DEFAULT_KEY_TEMPLATE).includes("{revision_key}")
-    ).map(([id]) => id);
-    if (unsafe.length > 0) {
-      throw new import_row_storage_errors.ReportingRowStoreError(
-        "INVALID_INPUT",
-        `snapshot compaction requires every object row binding's keyTemplate to include {revision_key}; binding(s) ${unsafe.join(", ")} omit it, so two revisions with identical content could share an object that compaction deletes while a concurrent commit adopts it`
-      );
-    }
-  }
-  /** IDs of the object bindings this host configures, the only ones it can delete objects through. */
-  objectBindingIds() {
-    return Object.entries(this.bindings).filter(([, binding]) => binding.kind === "object").map(([id]) => id);
-  }
-  /** 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 = (0, import_row_encoding.encodeReportingRowsV1)(input.rows);
-    } catch (error) {
-      if ((0, import_row_encoding.isReportingRowEncodingError)(error)) throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", error.message);
-      throw error;
-    }
-    const digestProfile = input.rowSetKind === "revision" ? "revision_envelope_v1" : "rows_v1";
-    const hasher = digestProfile === "revision_envelope_v1" ? (0, import_row_encoding.createReportingRevisionEnvelopeHasherV1)({
-      reporting_revision_id: input.rowSetId,
-      row_count: input.rows.length,
-      control_totals: input.controlTotals ?? []
-    }) : (0, import_row_encoding.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 import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "rows do not reproduce their committed binding");
-    }
-    const writable = Object.keys(this.bindings).filter((id) => {
-      const candidate = this.bindings[id];
-      return candidate.kind !== "object" || candidate.readOnly !== true;
-    });
-    if (writable.length === 0 && !input.bindingId && !this.options.selectRowBinding) {
-      throw new import_row_storage_errors.ReportingRowStoreError(
-        "UNSAFE_BINDING",
-        "no writable row binding is configured: every binding is readOnly"
-      );
-    }
-    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,
-      content_size_bytes: digest.byteCount
-    }) : writable.length === 1 ? writable[0] : DEFAULT_BINDING_ID;
-    const binding = this.bindings[bindingId];
-    if (!binding) throw new import_row_storage_errors.ReportingRowStoreError("STATE_UNAVAILABLE", `row binding ${bindingId} is not configured`);
-    if (binding.kind === "object" && binding.readOnly === true) {
-      throw new import_row_storage_errors.ReportingRowStoreError(
-        "UNSAFE_BINDING",
-        `row binding ${bindingId} is read-only and cannot take new row sets`
-      );
-    }
-    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" ? (0, import_zlib.gzipSync)(chunk.bytes, { level: 6 }) : chunk.bytes;
-      return Object.freeze({
-        objectRef: (0, import_row_storage_object.renderReportingRowObjectKeyV1)({
-          template: binding.keyTemplate ?? import_row_storage_object.REPORTING_ROW_DEFAULT_KEY_TEMPLATE,
-          prefix: binding.prefix,
-          namespaceKey,
-          accountId: input.accountId,
-          rowSetId: input.rowSetId,
-          ...input.periodStart ? { periodStart: input.periodStart } : {},
-          ...input.sourceTimezone ? { sourceTimezone: input.sourceTimezone } : {},
-          ...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 import_row_storage_errors.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,
-            objectRef: object.objectRef,
-            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({ objectRef: object.objectRef, nativeVersionRef: put.nativeVersionRef });
-        assertNativeVersionRef(put.nativeVersionRef);
-        locators.push({
-          objectRef: object.objectRef,
-          nativeVersionRef: put.nativeVersionRef,
-          compression: object.compression,
-          physicalSha256: object.physicalSha256,
-          sizeBytes: object.physicalBytes.byteLength,
-          created: true
-        });
-        continue;
-      }
-      assertNativeVersionRef(put.nativeVersionRef);
-      const existing = await this.provider(
-        () => provider.get(
-          {
-            ...location,
-            objectRef: object.objectRef,
-            nativeVersionRef: put.nativeVersionRef,
-            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 import_row_storage_errors.ReportingRowStoreError("CONTENT_CONFLICT", `object for chunk ${index} holds different bytes`);
-      }
-      locators.push({
-        objectRef: object.objectRef,
-        nativeVersionRef: put.nativeVersionRef,
-        compression: object.compression,
-        physicalSha256: sha256Hex(existing),
-        sizeBytes: 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 import_row_storage_errors.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, format, algorithm, digest_profile, content_sha256,
-          content_size_bytes, 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, $14)
-       ON CONFLICT (row_set_id) DO NOTHING`,
-      [
-        input.rowSetId,
-        input.rowSetKind,
-        input.accountId,
-        input.obligationId,
-        import_row_encoding.REPORTING_ROW_FORMAT_V1,
-        import_row_encoding.REPORTING_ROW_ALGORITHM_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 import_row_storage_errors.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, canonical_size_bytes, sha256,
-            segments, object_ref, native_version_ref, compression, physical_sha256, size_bytes)
-         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?.objectRef ?? null,
-          locator?.nativeVersionRef ?? null,
-          locator?.compression ?? "none",
-          locator?.physicalSha256 ?? null,
-          locator?.sizeBytes ?? 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.content_size_bytes, 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 import_row_storage_errors.ReportingRowStoreError("ROWS_EXPIRED");
-    }
-    if (record.rows_state === "unavailable") throw new import_row_storage_errors.ReportingRowStoreError("ROWS_UNAVAILABLE");
-    const chunks = await queryable.query(
-      `SELECT chunk_index, first_ordinal, row_count, canonical_size_bytes, sha256, segments,
-              object_ref, native_version_ref, compression, physical_sha256, size_bytes
-         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.canonical_size_bytes),
-      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 {
-      (0, import_row_encoding.verifyReportingRowManifestsV1)(manifests, { rowCount, rowManifestSha256: record.row_manifest_sha256 });
-    } catch (error) {
-      if ((0, import_row_encoding.isReportingRowEncodingError)(error)) throw new import_row_storage_errors.ReportingRowStoreError("ROWS_INTEGRITY_FAILED", error.message);
-      throw error;
-    }
-    if (manifests.length !== record.chunk_count) {
-      throw new import_row_storage_errors.ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "chunk count does not match the row set");
-    }
-    const locators = chunks.rows.map((chunk) => {
-      const hasLocation = chunk.object_ref !== null;
-      if (hasLocation !== (record.kind === "object")) {
-        throw new import_row_storage_errors.ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "chunk location does not match its binding kind");
-      }
-      return hasLocation ? Object.freeze({
-        objectRef: chunk.object_ref,
-        nativeVersionRef: chunk.native_version_ref,
-        compression: chunk.compression,
-        physicalSha256: chunk.physical_sha256,
-        sizeBytes: Number(chunk.size_bytes)
-      }) : 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,
-      contentSizeBytes: Number(record.content_size_bytes),
-      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 import_row_storage_errors.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(() => (0, import_row_encoding.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.contentSizeBytes > options.maxBytes) {
-      throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "row set exceeds the hydration byte limit");
-    }
-    const hasher = handle.digestProfile === "revision_envelope_v1" ? (0, import_row_encoding.createReportingRevisionEnvelopeHasherV1)({
-      reporting_revision_id: handle.rowSetId,
-      row_count: handle.rowCount,
-      control_totals: controlTotals ?? []
-    }) : (0, import_row_encoding.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(() => (0, import_row_encoding.verifyReportingRowChunkV1)(manifest, bytes));
-      hasher.update(bytes);
-      rows.push(
-        ...this.decode(() => (0, import_row_encoding.decodeVerifiedReportingRowSegmentsV1)(manifest, [0, manifest.segments.length - 1], bytes))
-      );
-    }
-    const digest = this.decode(() => hasher.digest());
-    if (digest.sha256 !== handle.contentSha256 || digest.byteCount !== handle.contentSizeBytes) {
-      throw new import_row_storage_errors.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 import_row_storage_errors.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.objectRef.startsWith(ownedPrefix)) {
-        throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "refusing to delete an object outside the owned prefix");
-      }
-      await this.provider(
-        () => provider.delete(
-          { ...providerLocation(binding), objectRef: object.objectRef, nativeVersionRef: object.nativeVersionRef },
-          context
-        )
-      );
-    }
-  }
-  /**
-   * Prove each object is still present at its recorded version with the recorded size.
-   * A commit that adopted an object another row set created calls this under the object's
-   * lock, so a concurrent delete either finished first (this throws, the commit fails and
-   * the writer re-uploads) or sees the commit's chunk reference and skips the delete.
-   *
-   * Native versions are write-unique (S3 VersionId, Azure versionId, GCS generation, filesystem
-   * `ino:birthtime:mtime:size`), so a version-pinned metadata check, "this exact version exists at the
-   * recorded size", proves the object unchanged without downloading it while the commit holds its
-   * locks. Bytes were verified when the object was uploaded or adopted. A custom provider without
-   * `stat` falls back to reading the whole object and comparing its physical digest.
-   */
-  async assertObjectsPresent(bindingId, objects, signal) {
-    await this.ready();
-    const binding = this.bindings[bindingId];
-    if (!binding || binding.kind !== "object") {
-      throw new import_row_storage_errors.ReportingRowStoreError("STATE_UNAVAILABLE", `row binding ${bindingId} is not configured for objects`);
-    }
-    const provider = this.providers[binding.provider];
-    const context = { signal: deadlineSignal(this.writeDeadline, signal) };
-    const location = providerLocation(binding);
-    const changed = () => new import_row_storage_errors.ReportingRowStoreError(
-      "STATE_UNAVAILABLE",
-      "an adopted row object was deleted or replaced before its commit; retry the upload"
-    );
-    for (const object of objects) {
-      const identity = { ...location, objectRef: object.objectRef, nativeVersionRef: object.nativeVersionRef };
-      if (provider.stat) {
-        const stat = await this.provider(() => provider.stat(identity, context));
-        if (!stat || stat.nativeVersionRef !== object.nativeVersionRef || !Number.isSafeInteger(stat.sizeBytes) || stat.sizeBytes !== object.sizeBytes) {
-          throw changed();
-        }
-        continue;
-      }
-      const bytes = await this.provider(
-        () => provider.get({ ...identity, maxBytes: MAX_ADOPTED_OBJECT_BYTES }, context)
-      );
-      if (!bytes || sha256Hex(bytes) !== object.physicalSha256) throw changed();
-    }
-  }
-  /**
-   * 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_ref, native_version_ref, compression, physical_sha256, size_bytes
-         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_ref === null)) return void 0;
-    return {
-      rowSetId,
-      locators: chunks.rows.map((chunk) => ({
-        objectRef: chunk.object_ref,
-        nativeVersionRef: chunk.native_version_ref,
-        compression: chunk.compression,
-        physicalSha256: chunk.physical_sha256,
-        sizeBytes: Number(chunk.size_bytes),
-        created: false
-      }))
-    };
-  }
-  /** Installation identity and namespace key; available after `ready()`. */
-  get installationIdentity() {
-    if (!this.installation) throw new import_row_storage_errors.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 import_row_storage_errors.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 import_row_storage_errors.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,
-            objectRef: locator.objectRef,
-            nativeVersionRef: locator.nativeVersionRef,
-            range: { offset: byteOffset, length: byteCount },
-            maxBytes: byteCount
-          },
-          context
-        )
-      );
-      if (!bytes)
-        throw new import_row_storage_errors.ReportingRowStoreError("ROWS_UNAVAILABLE", `chunk ${manifest.chunk_index} object is missing`);
-      if (bytes.byteLength !== byteCount) {
-        throw new import_row_storage_errors.ReportingRowStoreError("ROWS_INTEGRITY_FAILED", `chunk ${manifest.chunk_index} range is truncated`);
-      }
-      return Buffer.from(bytes);
-    }
-    const stored = await this.provider(
-      () => provider.get(
-        {
-          ...location,
-          objectRef: locator.objectRef,
-          nativeVersionRef: locator.nativeVersionRef,
-          maxBytes: locator.sizeBytes
-        },
-        context
-      )
-    );
-    if (!stored)
-      throw new import_row_storage_errors.ReportingRowStoreError("ROWS_UNAVAILABLE", `chunk ${manifest.chunk_index} object is missing`);
-    const physical = Buffer.from(stored);
-    if (physical.byteLength !== locator.sizeBytes || sha256Hex(physical) !== locator.physicalSha256) {
-      throw new import_row_storage_errors.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 import_row_storage_errors.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 = (0, import_zlib.gunzipSync)(physical, { maxOutputLength: byteCount });
-      return logical.byteLength === byteCount ? logical : null;
-    } catch {
-      return null;
-    }
-  }
-  decode(operation) {
-    try {
-      return operation();
-    } catch (error) {
-      if ((0, import_row_encoding.isReportingRowEncodingError)(error)) throw new import_row_storage_errors.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 ((0, import_row_storage_errors.isReportingRowStoreError)(error)) throw error;
-      if (error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError")) {
-        throw new import_row_storage_errors.ReportingRowStoreError(error.name === "TimeoutError" ? "DEADLINE_EXCEEDED" : "ABORTED");
-      }
-      throw new import_row_storage_errors.ReportingRowStoreError("PROVIDER_UNAVAILABLE");
-    }
-  }
-  async register() {
-    this.assertBindingKeyTemplates();
-    const { installationId } = await (0, import_row_storage_migration.probeReportingRowStorageSchemaV1)(this.pool);
-    const namespaceKey = sha256Hex((0, import_jcs.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 import_row_storage_errors.ReportingRowStoreError(
-          "UNSAFE_BINDING",
-          `row binding ${bindingId} identity differs from its definition`
-        );
-      }
-      if (row.namespace_key !== namespaceKey) {
-        throw new import_row_storage_errors.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 ?? import_row_storage_object.REPORTING_ROW_DEFAULT_KEY_TEMPLATE
-  } : {};
-}
-function bindingIdentitySha256(binding) {
-  const provider = binding.kind === "object" ? binding.provider : binding.kind;
-  return sha256Hex((0, import_jcs.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 assertNativeVersionRef(value) {
-  if (typeof value !== "string" || value.length < 1 || value.length > import_row_storage_object.REPORTING_ROW_NATIVE_VERSION_REF_MAX_LENGTH) {
-    throw new import_row_storage_errors.ReportingRowStoreError("PROVIDER_UNAVAILABLE", "provider returned an invalid native version reference");
-  }
-}
-function positiveMilliseconds(value, name) {
-  if (!Number.isSafeInteger(value) || value < 1e3 || value > 6e5) {
-    throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", `${name} must be between 1000 and 600000`);
-  }
-  return value;
-}
-function sha256Hex(value) {
-  return (0, import_crypto.createHash)("sha256").update(value).digest("hex");
-}
-function reportingRowWriteIntentIdV1() {
-  return (0, import_crypto.randomUUID)();
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  ReportingRowStorageV1,
-  ReportingRowStoreError,
-  isReportingRowStoreError,
-  reportingRowWriteIntentIdV1
-});