@adcp/sdk 15.5.0 → 15.6.0

package/dist/lib/reporting/azure/index.js

@@ -0,0 +1,247 @@
+"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 azure_exports = {};
+__export(azure_exports, {
+  createAzureBlobReportingRowObjectProviderV1: () => createAzureBlobReportingRowObjectProviderV1
+});
+module.exports = __toCommonJS(azure_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 ACCOUNT = /^[a-z0-9]{3,24}$/;
+const CONTAINER = /^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){2,62}$/;
+const VERSION_ID = /^[0-9A-Za-z:.+-]{1,64}$/;
+function statusOf(error) {
+  const status = Number(error?.statusCode);
+  return Number.isInteger(status) ? status : void 0;
+}
+function codeOf(error) {
+  const value = error?.code ?? error?.details?.errorCode;
+  return typeof value === "string" ? value : "";
+}
+const isConflict = (error) => statusOf(error) === 409 || statusOf(error) === 412 || codeOf(error) === "BlobAlreadyExists";
+const isMissing = (error) => statusOf(error) === 404 || statusOf(error) === 412;
+const isForbidden = (error) => statusOf(error) === 401 || statusOf(error) === 403;
+function versionOf(response) {
+  const id = response.versionId;
+  if (typeof id !== "string" || !VERSION_ID.test(id)) {
+    throw new import_row_storage_errors.ReportingRowStoreError(
+      "UNSAFE_BINDING",
+      "store returned no blob versionId; blob versioning must be enabled on the storage account so deletes are fenced to one write"
+    );
+  }
+  return id;
+}
+function servedVersion(response, versionId) {
+  return response.versionId === versionId;
+}
+function metadataOf(metadata) {
+  const result = {};
+  for (const [name, value] of Object.entries(metadata)) {
+    const identifier = name.replace(/[^A-Za-z0-9_]/g, "_");
+    result[/^[A-Za-z_]/.test(identifier) ? identifier : `_${identifier}`] = value;
+  }
+  return result;
+}
+function createAzureBlobReportingRowObjectProviderV1(options) {
+  if (!options || typeof options !== "object") {
+    throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "Azure Blob row provider options are required");
+  }
+  const clients = (0, import_row_storage_provider_io.reportingRowClientMap)(options.clients);
+  const isClient = (value) => !!value && typeof value === "object" && typeof value.getContainerClient === "function" && typeof value.accountName === "string";
+  if (options.client !== void 0 && !isClient(options.client) || [...clients.values()].some((client) => !isClient(client)) || options.client === void 0 && clients.size === 0) {
+    throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "inject an official BlobServiceClient as client or clients");
+  }
+  const validateLocation = (location) => {
+    (0, import_row_storage_provider_io.assertReportingRowLocationKeys)(location, ["account", "container"]);
+    if (!ACCOUNT.test(location.account)) {
+      throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "Azure storage account name is invalid");
+    }
+    if (!CONTAINER.test(location.container)) {
+      throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "Azure container name is invalid");
+    }
+  };
+  const containerFor = (input) => {
+    validateLocation(input.location);
+    const client = (0, import_row_storage_provider_io.selectReportingRowClient)(options.client, clients, input.credentialRef);
+    if (client.accountName !== input.location.account) {
+      throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "client does not belong to the binding account");
+    }
+    return client.getContainerClient(input.location.container);
+  };
+  const blobFor = (input) => {
+    if (typeof input.key !== "string" || input.key.length === 0 || input.key.length > 1024) {
+      throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "object key is invalid");
+    }
+    return containerFor(input).getBlockBlobClient(input.key);
+  };
+  const pinned = (blob, nativeVersion) => typeof nativeVersion === "string" && VERSION_ID.test(nativeVersion) ? { blob: blob.withVersion(nativeVersion), versionId: nativeVersion } : null;
+  async function assertCreateOnlyEnforced(container, prefix, signal) {
+    const blob = container.getBlockBlobClient(`${prefix}/.adcp-probe/${(0, import_node_crypto.randomUUID)()}`);
+    const versionIds = [];
+    let written = false;
+    const upload = async (body) => {
+      const bytes = Buffer.from(body);
+      const response = await blob.upload(bytes, bytes.byteLength, {
+        conditions: { ifNoneMatch: "*" },
+        blobHTTPHeaders: { blobContentType: "application/x-ndjson", blobCacheControl: "no-store" },
+        abortSignal: signal
+      });
+      written = true;
+      if (response.versionId) versionIds.push(response.versionId);
+      versionOf(response);
+    };
+    try {
+      await upload('{"probe":1}\n');
+      try {
+        await upload('{"probe":2}\n');
+      } catch (error) {
+        if (isConflict(error)) return;
+        throw error;
+      }
+      throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "store ignores If-None-Match and replaces blobs");
+    } finally {
+      if (written && !signal.aborted) {
+        await blob.delete({ abortSignal: signal }).catch(() => void 0);
+        for (const versionId of versionIds) {
+          if (signal.aborted) break;
+          await blob.withVersion(versionId).delete({ abortSignal: signal }).catch(() => void 0);
+        }
+      }
+    }
+  }
+  return {
+    name: "azure_blob",
+    rangedReads: true,
+    validateLocation,
+    probe(input, context) {
+      return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
+        const container = containerFor(input);
+        let properties;
+        try {
+          properties = await container.getProperties({ abortSignal: context.signal });
+        } catch (error) {
+          if (statusOf(error) === 404) throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "container does not exist");
+          if (isForbidden(error)) throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "container is not accessible");
+          throw error;
+        }
+        if (properties.blobPublicAccess) {
+          throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "container allows anonymous read access");
+        }
+        await assertCreateOnlyEnforced(container, input.prefix, context.signal);
+      });
+    },
+    putIfAbsent(input, context) {
+      return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
+        const blob = blobFor(input);
+        const bytes = Buffer.from(input.bytes);
+        try {
+          const response = await blob.upload(bytes, bytes.byteLength, {
+            conditions: { ifNoneMatch: "*" },
+            blobHTTPHeaders: { blobContentType: input.contentType, blobCacheControl: "no-store" },
+            metadata: metadataOf(input.metadata),
+            abortSignal: context.signal
+          });
+          return { created: true, nativeVersion: versionOf(response) };
+        } catch (error) {
+          if (!isConflict(error)) throw error;
+        }
+        const existing = await blob.getProperties({ abortSignal: context.signal });
+        return { created: false, nativeVersion: versionOf(existing) };
+      });
+    },
+    get(input, context) {
+      return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
+        const blob = blobFor(input);
+        (0, import_row_storage_provider_io.assertReportingRowReadBounds)(input);
+        const target = pinned(blob, input.nativeVersion);
+        if (target === null) return null;
+        try {
+          if (input.range?.length === 0) {
+            const properties = await target.blob.getProperties({ abortSignal: context.signal });
+            if (!servedVersion(properties, target.versionId)) return null;
+            if (input.range.offset > Number(properties.contentLength ?? 0)) {
+              throw new import_row_storage_errors.ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "requested range exceeds the stored object");
+            }
+            return Buffer.alloc(0);
+          }
+          const response = await target.blob.download(input.range?.offset ?? 0, input.range?.length, {
+            abortSignal: context.signal
+          });
+          const body = response.readableStreamBody;
+          if (!body || typeof body[Symbol.asyncIterator] !== "function") {
+            throw new import_row_storage_errors.ReportingRowStoreError("PROVIDER_UNAVAILABLE", "blob body is not a stream");
+          }
+          if (!servedVersion(response, target.versionId)) {
+            body.destroy?.();
+            return null;
+          }
+          if (typeof response.contentLength === "number" && response.contentLength > input.maxBytes) {
+            body.destroy?.();
+            throw new import_row_storage_errors.ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "stored object exceeds its recorded size");
+          }
+          return await (0, import_row_storage_provider_io.readReportingRowStream)(body, input.maxBytes, context.signal);
+        } catch (error) {
+          if (isMissing(error)) return null;
+          if (statusOf(error) === 400) return null;
+          if (statusOf(error) === 416 || codeOf(error) === "InvalidRange") {
+            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 blob = blobFor(input);
+        const target = pinned(blob, input.nativeVersion);
+        if (target === null) return "absent";
+        const signal = context.signal;
+        try {
+          const recorded = await target.blob.getProperties({ abortSignal: signal });
+          if (recorded.versionId !== target.versionId) return "absent";
+        } catch (error) {
+          if (isMissing(error) || statusOf(error) === 400) return "absent";
+          throw error;
+        }
+        let deletedCurrent = false;
+        try {
+          const current = await blob.getProperties({ abortSignal: signal });
+          if (current.versionId === target.versionId && current.etag) {
+            await blob.delete({ conditions: { ifMatch: current.etag }, abortSignal: signal });
+            deletedCurrent = true;
+          }
+        } catch (error) {
+          if (!isMissing(error)) throw error;
+        }
+        try {
+          await target.blob.delete({ abortSignal: signal });
+          return "deleted";
+        } catch (error) {
+          if (isMissing(error) || statusOf(error) === 400) return deletedCurrent ? "deleted" : "absent";
+          throw error;
+        }
+      });
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createAzureBlobReportingRowObjectProviderV1
+});

package/dist/lib/reporting/azure/index.mjs

@@ -0,0 +1,230 @@
+import { randomUUID } from "node:crypto";
+import { ReportingRowStoreError } from "../ledger/row-storage-errors.mjs";
+import {
+  assertReportingRowLocationKeys,
+  assertReportingRowReadBounds,
+  readReportingRowStream,
+  reportingRowClientMap,
+  runReportingRowProviderOperation,
+  selectReportingRowClient
+} from "../ledger/row-storage-provider-io.mjs";
+const ACCOUNT = /^[a-z0-9]{3,24}$/;
+const CONTAINER = /^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){2,62}$/;
+const VERSION_ID = /^[0-9A-Za-z:.+-]{1,64}$/;
+function statusOf(error) {
+  const status = Number(error?.statusCode);
+  return Number.isInteger(status) ? status : void 0;
+}
+function codeOf(error) {
+  const value = error?.code ?? error?.details?.errorCode;
+  return typeof value === "string" ? value : "";
+}
+const isConflict = (error) => statusOf(error) === 409 || statusOf(error) === 412 || codeOf(error) === "BlobAlreadyExists";
+const isMissing = (error) => statusOf(error) === 404 || statusOf(error) === 412;
+const isForbidden = (error) => statusOf(error) === 401 || statusOf(error) === 403;
+function versionOf(response) {
+  const id = response.versionId;
+  if (typeof id !== "string" || !VERSION_ID.test(id)) {
+    throw new ReportingRowStoreError(
+      "UNSAFE_BINDING",
+      "store returned no blob versionId; blob versioning must be enabled on the storage account so deletes are fenced to one write"
+    );
+  }
+  return id;
+}
+function servedVersion(response, versionId) {
+  return response.versionId === versionId;
+}
+function metadataOf(metadata) {
+  const result = {};
+  for (const [name, value] of Object.entries(metadata)) {
+    const identifier = name.replace(/[^A-Za-z0-9_]/g, "_");
+    result[/^[A-Za-z_]/.test(identifier) ? identifier : `_${identifier}`] = value;
+  }
+  return result;
+}
+function createAzureBlobReportingRowObjectProviderV1(options) {
+  if (!options || typeof options !== "object") {
+    throw new ReportingRowStoreError("INVALID_INPUT", "Azure Blob row provider options are required");
+  }
+  const clients = reportingRowClientMap(options.clients);
+  const isClient = (value) => !!value && typeof value === "object" && typeof value.getContainerClient === "function" && typeof value.accountName === "string";
+  if (options.client !== void 0 && !isClient(options.client) || [...clients.values()].some((client) => !isClient(client)) || options.client === void 0 && clients.size === 0) {
+    throw new ReportingRowStoreError("INVALID_INPUT", "inject an official BlobServiceClient as client or clients");
+  }
+  const validateLocation = (location) => {
+    assertReportingRowLocationKeys(location, ["account", "container"]);
+    if (!ACCOUNT.test(location.account)) {
+      throw new ReportingRowStoreError("INVALID_INPUT", "Azure storage account name is invalid");
+    }
+    if (!CONTAINER.test(location.container)) {
+      throw new ReportingRowStoreError("INVALID_INPUT", "Azure container name is invalid");
+    }
+  };
+  const containerFor = (input) => {
+    validateLocation(input.location);
+    const client = selectReportingRowClient(options.client, clients, input.credentialRef);
+    if (client.accountName !== input.location.account) {
+      throw new ReportingRowStoreError("UNSAFE_BINDING", "client does not belong to the binding account");
+    }
+    return client.getContainerClient(input.location.container);
+  };
+  const blobFor = (input) => {
+    if (typeof input.key !== "string" || input.key.length === 0 || input.key.length > 1024) {
+      throw new ReportingRowStoreError("INVALID_INPUT", "object key is invalid");
+    }
+    return containerFor(input).getBlockBlobClient(input.key);
+  };
+  const pinned = (blob, nativeVersion) => typeof nativeVersion === "string" && VERSION_ID.test(nativeVersion) ? { blob: blob.withVersion(nativeVersion), versionId: nativeVersion } : null;
+  async function assertCreateOnlyEnforced(container, prefix, signal) {
+    const blob = container.getBlockBlobClient(`${prefix}/.adcp-probe/${randomUUID()}`);
+    const versionIds = [];
+    let written = false;
+    const upload = async (body) => {
+      const bytes = Buffer.from(body);
+      const response = await blob.upload(bytes, bytes.byteLength, {
+        conditions: { ifNoneMatch: "*" },
+        blobHTTPHeaders: { blobContentType: "application/x-ndjson", blobCacheControl: "no-store" },
+        abortSignal: signal
+      });
+      written = true;
+      if (response.versionId) versionIds.push(response.versionId);
+      versionOf(response);
+    };
+    try {
+      await upload('{"probe":1}\n');
+      try {
+        await upload('{"probe":2}\n');
+      } catch (error) {
+        if (isConflict(error)) return;
+        throw error;
+      }
+      throw new ReportingRowStoreError("UNSAFE_BINDING", "store ignores If-None-Match and replaces blobs");
+    } finally {
+      if (written && !signal.aborted) {
+        await blob.delete({ abortSignal: signal }).catch(() => void 0);
+        for (const versionId of versionIds) {
+          if (signal.aborted) break;
+          await blob.withVersion(versionId).delete({ abortSignal: signal }).catch(() => void 0);
+        }
+      }
+    }
+  }
+  return {
+    name: "azure_blob",
+    rangedReads: true,
+    validateLocation,
+    probe(input, context) {
+      return runReportingRowProviderOperation(context.signal, async () => {
+        const container = containerFor(input);
+        let properties;
+        try {
+          properties = await container.getProperties({ abortSignal: context.signal });
+        } catch (error) {
+          if (statusOf(error) === 404) throw new ReportingRowStoreError("UNSAFE_BINDING", "container does not exist");
+          if (isForbidden(error)) throw new ReportingRowStoreError("UNSAFE_BINDING", "container is not accessible");
+          throw error;
+        }
+        if (properties.blobPublicAccess) {
+          throw new ReportingRowStoreError("UNSAFE_BINDING", "container allows anonymous read access");
+        }
+        await assertCreateOnlyEnforced(container, input.prefix, context.signal);
+      });
+    },
+    putIfAbsent(input, context) {
+      return runReportingRowProviderOperation(context.signal, async () => {
+        const blob = blobFor(input);
+        const bytes = Buffer.from(input.bytes);
+        try {
+          const response = await blob.upload(bytes, bytes.byteLength, {
+            conditions: { ifNoneMatch: "*" },
+            blobHTTPHeaders: { blobContentType: input.contentType, blobCacheControl: "no-store" },
+            metadata: metadataOf(input.metadata),
+            abortSignal: context.signal
+          });
+          return { created: true, nativeVersion: versionOf(response) };
+        } catch (error) {
+          if (!isConflict(error)) throw error;
+        }
+        const existing = await blob.getProperties({ abortSignal: context.signal });
+        return { created: false, nativeVersion: versionOf(existing) };
+      });
+    },
+    get(input, context) {
+      return runReportingRowProviderOperation(context.signal, async () => {
+        const blob = blobFor(input);
+        assertReportingRowReadBounds(input);
+        const target = pinned(blob, input.nativeVersion);
+        if (target === null) return null;
+        try {
+          if (input.range?.length === 0) {
+            const properties = await target.blob.getProperties({ abortSignal: context.signal });
+            if (!servedVersion(properties, target.versionId)) return null;
+            if (input.range.offset > Number(properties.contentLength ?? 0)) {
+              throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "requested range exceeds the stored object");
+            }
+            return Buffer.alloc(0);
+          }
+          const response = await target.blob.download(input.range?.offset ?? 0, input.range?.length, {
+            abortSignal: context.signal
+          });
+          const body = response.readableStreamBody;
+          if (!body || typeof body[Symbol.asyncIterator] !== "function") {
+            throw new ReportingRowStoreError("PROVIDER_UNAVAILABLE", "blob body is not a stream");
+          }
+          if (!servedVersion(response, target.versionId)) {
+            body.destroy?.();
+            return null;
+          }
+          if (typeof response.contentLength === "number" && response.contentLength > input.maxBytes) {
+            body.destroy?.();
+            throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "stored object exceeds its recorded size");
+          }
+          return await readReportingRowStream(body, input.maxBytes, context.signal);
+        } catch (error) {
+          if (isMissing(error)) return null;
+          if (statusOf(error) === 400) return null;
+          if (statusOf(error) === 416 || codeOf(error) === "InvalidRange") {
+            throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "requested range exceeds the stored object");
+          }
+          throw error;
+        }
+      });
+    },
+    delete(input, context) {
+      return runReportingRowProviderOperation(context.signal, async () => {
+        const blob = blobFor(input);
+        const target = pinned(blob, input.nativeVersion);
+        if (target === null) return "absent";
+        const signal = context.signal;
+        try {
+          const recorded = await target.blob.getProperties({ abortSignal: signal });
+          if (recorded.versionId !== target.versionId) return "absent";
+        } catch (error) {
+          if (isMissing(error) || statusOf(error) === 400) return "absent";
+          throw error;
+        }
+        let deletedCurrent = false;
+        try {
+          const current = await blob.getProperties({ abortSignal: signal });
+          if (current.versionId === target.versionId && current.etag) {
+            await blob.delete({ conditions: { ifMatch: current.etag }, abortSignal: signal });
+            deletedCurrent = true;
+          }
+        } catch (error) {
+          if (!isMissing(error)) throw error;
+        }
+        try {
+          await target.blob.delete({ abortSignal: signal });
+          return "deleted";
+        } catch (error) {
+          if (isMissing(error) || statusOf(error) === 400) return deletedCurrent ? "deleted" : "absent";
+          throw error;
+        }
+      });
+    }
+  };
+}
+export {
+  createAzureBlobReportingRowObjectProviderV1
+};

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

@@ -0,0 +1,127 @@
+import type { PostgresReportingLedgerStore, ReportingLedgerRevisionMetadataV1, ReportingPgPool } from '../ledger/index.mjs';
+/**
+ * BigQuery warehouse sink for Reliable Reporting (shared SDK persistence spec,
+ * adcontextprotocol/adcp#7996 §3.6).
+ *
+ * The sink is a derived, non-authoritative copy of committed revisions. It
+ * follows the ledger's host change feed, reads every revision's rows through
+ * the store's verified reader, maps them to the adopter's columns, and loads
+ * one batch per tick with a deterministic job ID. It is never read for
+ * serving or verification, so its tables, columns, partitioning and retention
+ * are the adopter's.
+ *
+ * Exactly-once loading: a batch (change-feed range, revision list, job IDs) is
+ * planned durably in PostgreSQL before any load. A crash between the load and
+ * the cursor commit replays the same batch under the same job IDs, which
+ * BigQuery refuses to run twice. A failed load job is retried under a new
+ * attempt suffix only after BigQuery reports that job finished with an error,
+ * and each table keeps its own attempt count, so no batch lands twice.
+ */
+/** Apply after `REPORTING_LEDGER_CHANGES_MIGRATION`. Holds one row per sink. */
+export declare const REPORTING_WAREHOUSE_SINK_MIGRATION: string;
+/** Structural subset of the official `@google-cloud/bigquery` client the sink uses. */
+export interface ReportingBigQueryClientV1 {
+    dataset(datasetId: string, options?: {
+        projectId?: string;
+        location?: string;
+    }): {
+        table(tableId: string): {
+            load(source: string, metadata: Record<string, unknown>): Promise<unknown>;
+        };
+    };
+    job(jobId: string, options?: {
+        location?: string;
+    }): {
+        getMetadata(): Promise<unknown>;
+    };
+    query(options: {
+        query: string;
+        location?: string;
+    }): Promise<unknown>;
+}
+export interface ReportingWarehouseRowContextV1 {
+    revision: ReportingLedgerRevisionMetadataV1;
+    ordinal: number;
+}
+export interface CreateBigQueryReportingWarehouseSinkOptionsV1 {
+    /** Ledger store with `changeFeed: true`. */
+    store: Pick<PostgresReportingLedgerStore, 'changesAfter' | 'saveFeedConsumerCursor' | 'getRevisionMetadata' | 'readRevisionRows'>;
+    /** PostgreSQL pool holding `REPORTING_WAREHOUSE_SINK_MIGRATION`. */
+    db: Pick<ReportingPgPool, 'query'>;
+    /** Host-constructed official BigQuery client. */
+    bigquery: ReportingBigQueryClientV1;
+    /** Stable sink name; also the registered change-feed consumer name. */
+    name: string;
+    projectId?: string;
+    datasetId: string;
+    rowsTableId: string;
+    revisionsTableId: string;
+    /** Dataset location, so jobs run in the dataset's region. */
+    location?: string;
+    /** Restrict the sink to one account; omit for the deployment-wide feed. */
+    account_id?: string;
+    /**
+     * Map one verified report row to the adopter's columns. The sink always adds
+     * `reporting_revision_id`, `reporting_obligation_id`, `account_id`,
+     * `revision_number`, `finality`, `period_date` and `ordinal`. Default: the
+     * row as a `row` JSON column.
+     */
+    mapRow?(row: Record<string, unknown>, context: ReportingWarehouseRowContextV1): Record<string, unknown>;
+    /** Revisions per batch. Default 200. */
+    maxRevisionsPerBatch?: number;
+    /** Job labels for cost attribution. */
+    labels?: Readonly<Record<string, string>>;
+    /**
+     * Deadline for one load (and its status check). Default 10 minutes. It is
+     * also sent as the job's `jobTimeoutMs`. A run that times out leaves its
+     * plan in place; the next run reuses the same job ID and waits for, or
+     * accepts, the job BigQuery is still running.
+     */
+    loadTimeoutMilliseconds?: number;
+}
+export interface BigQueryReportingWarehouseSinkV1 {
+    /**
+     * Load at most one batch. Resolves with what was loaded; `idle` when nothing new committed.
+     *
+     * `missing` lists revision IDs the change feed announced that no longer
+     * exist in the ledger because their period was retired before this batch
+     * ran. That is a data-loss signal: the sink fell behind retention (it was
+     * down longer than `maxFeedHoldDays`, so retention stopped waiting for it)
+     * and the warehouse lacks those revisions. Backfill them from another source
+     * or accept the gap. The cursor still advances so the sink is not stuck.
+     * Alert on a non-empty `missing`. After a crash-and-replay of a planned
+     * batch, a listed revision may already have been loaded by the first attempt.
+     */
+    runOnce(options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        idle: boolean;
+        revisions: number;
+        rows: number;
+        missing: string[];
+    }>;
+    /** DDL for the default rows and revisions tables (partitioned and clustered). */
+    readonly defaultTablesSql: string;
+    /** DDL for the reference `current_rows` view. */
+    readonly currentRowsViewSql: string;
+}
+export declare function createBigQueryReportingWarehouseSinkV1(options: CreateBigQueryReportingWarehouseSinkOptionsV1): BigQueryReportingWarehouseSinkV1;
+/** Deterministic load job ID for one planned change-feed range. */
+export declare function reportingWarehouseJobIdV1(name: string, from: string | null, to: string): string;
+interface WarehouseTablesV1 {
+    projectId?: string;
+    datasetId: string;
+    rowsTableId: string;
+    revisionsTableId: string;
+}
+/** DDL for the default warehouse tables: partitioned by period date, clustered by account and revision. */
+export declare function reportingWarehouseDefaultTablesSqlV1(tables: WarehouseTablesV1): string;
+/**
+ * DDL for the reference `current_rows` view: only each obligation's current
+ * revision (its official revision, otherwise its latest snapshot). Summing
+ * cumulative snapshots across revisions double-counts; query this view.
+ */
+export declare function reportingWarehouseCurrentRowsViewSqlV1(tables: WarehouseTablesV1 & {
+    viewId?: string;
+}): string;
+export {};