@adcp/sdk 15.9.1 → 16.0.0-beta.2

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

@@ -24,9 +24,17 @@ import type { PostgresReportingLedgerStore, ReportingLedgerRevisionMetadataV1, R
  * Concurrent runs claim one durable plan with compare-and-swap. Replays of
  * that plan share job IDs; stale runs cannot change its attempts or cursor.
  */
-/** Apply after `REPORTING_LEDGER_CHANGES_MIGRATION`. Holds one row per sink. */
+/**
+ * Apply after `REPORTING_LEDGER_CHANGES_MIGRATION`. Holds one row per sink.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare const REPORTING_WAREHOUSE_SINK_MIGRATION: string;
-/** Structural subset of the official `@google-cloud/bigquery` client the sink uses. */
+/**
+ * Structural subset of the official `@google-cloud/bigquery` client the sink uses.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export interface ReportingBigQueryClientV1 {
     dataset(datasetId: string, options?: {
         projectId?: string;
@@ -49,10 +57,16 @@ export interface ReportingBigQueryClientV1 {
         location?: string;
     }): Promise<unknown>;
 }
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export interface ReportingWarehouseRowContextV1 {
     revision: ReportingLedgerRevisionMetadataV1;
     ordinal: number;
 }
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export interface CreateBigQueryReportingWarehouseSinkOptionsV1 {
     /** Ledger store with `changeFeed: true`. */
     store: Pick<PostgresReportingLedgerStore, 'changesAfter' | 'getRevisionMetadata' | 'readRevisionRows'> & {
@@ -90,7 +104,9 @@ export interface CreateBigQueryReportingWarehouseSinkOptionsV1 {
     /**
      * 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
+     * `revision_number`, `finality`, `period_date` (the period start's calendar date in its
+     * `source_timezone`, AdCP's `YYYY-MM-DD`; the batch fails if it cannot be computed) and
+     * `ordinal`. Default: the
      * row as a `row` JSON column.
      */
     mapRow?(row: Record<string, unknown>, context: ReportingWarehouseRowContextV1): Record<string, unknown>;
@@ -128,6 +144,9 @@ export interface CreateBigQueryReportingWarehouseSinkOptionsV1 {
      */
     loadTimeoutMilliseconds?: number;
 }
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export interface BigQueryReportingWarehouseSinkV1 {
     /**
      * Load at most one batch. Resolves with what was loaded; `idle` when no
@@ -185,13 +204,22 @@ export interface BigQueryReportingWarehouseSinkV1 {
     /** DDL for the reference `current_rows` view. */
     readonly currentRowsViewSql: string;
 }
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare function createBigQueryReportingWarehouseSinkV1(options: CreateBigQueryReportingWarehouseSinkOptionsV1): BigQueryReportingWarehouseSinkV1;
 /**
  * How long one run may upload a file or wait for a running job: the configured
  * base doubled once per earlier timeout of that table's load, capped at 6 hours.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
  */
 export declare function reportingWarehouseLoadDeadlineV1(baseMilliseconds: number, timeouts: number): number;
-/** Deterministic load job ID for one planned change-feed range. */
+/**
+ * Deterministic load job ID for one planned change-feed range.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare function reportingWarehouseJobIdV1(name: string, from: string | null, to: string, generation?: number): string;
 interface WarehouseTablesV1 {
     projectId?: string;
@@ -199,12 +227,18 @@ interface WarehouseTablesV1 {
     rowsTableId: string;
     revisionsTableId: string;
 }
-/** DDL for the default warehouse tables: partitioned by period date, clustered by account and revision. */
+/**
+ * DDL for the default warehouse tables: partitioned by period date, clustered by account and revision.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 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.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
  */
 export declare function reportingWarehouseCurrentRowsViewSqlV1(tables: WarehouseTablesV1 & {
     viewId?: string;

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

@@ -41,6 +41,7 @@ var import_fs = require("fs");
 var import_os = require("os");
 var path = __toESM(require("path"));
 var import_change_feed = require('../ledger/change-feed.js');
+var import_schedule = require('../ledger/schedule.js');
 const REPORTING_WAREHOUSE_SINK_MIGRATION = `
 CREATE TABLE IF NOT EXISTS adcp_reporting_warehouse_sinks (
   sink_name TEXT PRIMARY KEY CHECK (sink_name ~ '^[A-Za-z0-9_.:-]{1,128}$'),
@@ -66,6 +67,7 @@ ALTER TABLE adcp_reporting_warehouse_sinks
 const MAX_LOAD_TIMEOUT = 6 * 36e5;
 const MAX_TIMEOUT_DOUBLINGS = 16;
 let warnedLabelsIgnored = false;
+let warnedLocationUnset = false;
 const PROJECT = /^[a-z][a-z0-9-]{4,61}[a-z0-9]$/;
 const DATASET_OR_TABLE = /^[A-Za-z_][A-Za-z0-9_]{0,1023}$/;
 const NAME = /^[A-Za-z0-9_.:-]{1,128}$/;
@@ -96,6 +98,13 @@ function createBigQueryReportingWarehouseSinkV1(options) {
       { code: "ADCP_BIGQUERY_SINK_LABELS_IGNORED", type: "DeprecationWarning" }
     );
   }
+  if (!options.location && !warnedLocationUnset) {
+    warnedLocationUnset = true;
+    process.emitWarning(
+      'BigQuery warehouse sink option `location` is not set. Replay lookups of load jobs need it for datasets outside the US and EU multi-regions: without it BigQuery answers 404, the sink uploads again, gets a 409, and then fails with a "check projectId and location" error.',
+      { code: "ADCP_BIGQUERY_SINK_LOCATION_UNSET" }
+    );
+  }
   const tables = {
     projectId: options.projectId,
     datasetId: options.datasetId,
@@ -362,6 +371,7 @@ function createBigQueryReportingWarehouseSinkV1(options) {
       const rowLines = [];
       const revisionLines = [];
       const missing = [];
+      const resolved = [];
       for (const planned of plan.revisions) {
         signal?.throwIfAborted();
         const revision = await options.store.getRevisionMetadata(planned.id, planned.account_id);
@@ -369,10 +379,10 @@ function createBigQueryReportingWarehouseSinkV1(options) {
           missing.push(planned.id);
           continue;
         }
-        const periodDate = sourceLocalDate(
-          revision.wireRevision.period?.start,
-          revision.wireRevision.period?.source_timezone
-        );
+        resolved.push({ planned, revision, periodDate: periodDateOf(revision) });
+      }
+      for (const { planned, revision, periodDate } of resolved) {
+        signal?.throwIfAborted();
         const base = {
           reporting_revision_id: revision.reporting_revision_id,
           reporting_obligation_id: revision.reporting_obligation_id,
@@ -401,9 +411,9 @@ function createBigQueryReportingWarehouseSinkV1(options) {
           JSON.stringify({
             ...base,
             supersedes_reporting_revision_id: revision.supersedes_reporting_revision_id ?? null,
-            period_start: revision.wireRevision.period?.start ?? null,
-            period_end: revision.wireRevision.period?.end ?? null,
-            source_timezone: revision.wireRevision.period?.source_timezone ?? null,
+            period_start: revision.wireRevision.period.start,
+            period_end: revision.wireRevision.period.end,
+            source_timezone: revision.wireRevision.period.source_timezone,
             observed_at: revision.observedAt,
             data_through: revision.dataThrough,
             revision_content_sha256: revision.binding.sha256,
@@ -547,20 +557,16 @@ SELECT row_data.*
   ) AS current_revision
  USING (reporting_obligation_id, reporting_revision_id);`.trim();
 }
-function sourceLocalDate(start, timeZone) {
-  if (!start) return null;
-  const instant = new Date(start);
-  if (Number.isNaN(instant.getTime())) return null;
+function periodDateOf(revision) {
+  const period = revision.wireRevision.period;
   try {
-    const parts = new Intl.DateTimeFormat("en-CA", {
-      timeZone: timeZone ?? "UTC",
-      year: "numeric",
-      month: "2-digit",
-      day: "2-digit"
-    }).format(instant);
-    return parts;
-  } catch {
-    return instant.toISOString().slice(0, 10);
+    if (!period) throw new TypeError("the revision carries no period");
+    return (0, import_schedule.reportingPeriodDate)(period.start, period.source_timezone);
+  } catch (error) {
+    throw new Error(
+      `Cannot compute period_date for revision ${revision.reporting_revision_id}: ${error instanceof Error ? error.message : String(error)}. The batch stays retained and every run fails until the revision's period is repaired (or, if this runtime's timezone data is older than the writer's, until it is upgraded); reset({ discardRetainedPlan: true }) restarts from the beginning, so empty the destination tables first.`,
+      { cause: error }
+    );
   }
 }
 async function withinDeadline(operation, milliseconds, signal, context) {

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

@@ -3,6 +3,7 @@ import { promises as fs } from "fs";
 import { tmpdir } from "os";
 import * as path from "path";
 import { decodeReportingChangeCursorV1 } from "../ledger/change-feed.mjs";
+import { reportingPeriodDate } from "../ledger/schedule.mjs";
 const REPORTING_WAREHOUSE_SINK_MIGRATION = `
 CREATE TABLE IF NOT EXISTS adcp_reporting_warehouse_sinks (
   sink_name TEXT PRIMARY KEY CHECK (sink_name ~ '^[A-Za-z0-9_.:-]{1,128}$'),
@@ -28,6 +29,7 @@ ALTER TABLE adcp_reporting_warehouse_sinks
 const MAX_LOAD_TIMEOUT = 6 * 36e5;
 const MAX_TIMEOUT_DOUBLINGS = 16;
 let warnedLabelsIgnored = false;
+let warnedLocationUnset = false;
 const PROJECT = /^[a-z][a-z0-9-]{4,61}[a-z0-9]$/;
 const DATASET_OR_TABLE = /^[A-Za-z_][A-Za-z0-9_]{0,1023}$/;
 const NAME = /^[A-Za-z0-9_.:-]{1,128}$/;
@@ -58,6 +60,13 @@ function createBigQueryReportingWarehouseSinkV1(options) {
       { code: "ADCP_BIGQUERY_SINK_LABELS_IGNORED", type: "DeprecationWarning" }
     );
   }
+  if (!options.location && !warnedLocationUnset) {
+    warnedLocationUnset = true;
+    process.emitWarning(
+      'BigQuery warehouse sink option `location` is not set. Replay lookups of load jobs need it for datasets outside the US and EU multi-regions: without it BigQuery answers 404, the sink uploads again, gets a 409, and then fails with a "check projectId and location" error.',
+      { code: "ADCP_BIGQUERY_SINK_LOCATION_UNSET" }
+    );
+  }
   const tables = {
     projectId: options.projectId,
     datasetId: options.datasetId,
@@ -324,6 +333,7 @@ function createBigQueryReportingWarehouseSinkV1(options) {
       const rowLines = [];
       const revisionLines = [];
       const missing = [];
+      const resolved = [];
       for (const planned of plan.revisions) {
         signal?.throwIfAborted();
         const revision = await options.store.getRevisionMetadata(planned.id, planned.account_id);
@@ -331,10 +341,10 @@ function createBigQueryReportingWarehouseSinkV1(options) {
           missing.push(planned.id);
           continue;
         }
-        const periodDate = sourceLocalDate(
-          revision.wireRevision.period?.start,
-          revision.wireRevision.period?.source_timezone
-        );
+        resolved.push({ planned, revision, periodDate: periodDateOf(revision) });
+      }
+      for (const { planned, revision, periodDate } of resolved) {
+        signal?.throwIfAborted();
         const base = {
           reporting_revision_id: revision.reporting_revision_id,
           reporting_obligation_id: revision.reporting_obligation_id,
@@ -363,9 +373,9 @@ function createBigQueryReportingWarehouseSinkV1(options) {
           JSON.stringify({
             ...base,
             supersedes_reporting_revision_id: revision.supersedes_reporting_revision_id ?? null,
-            period_start: revision.wireRevision.period?.start ?? null,
-            period_end: revision.wireRevision.period?.end ?? null,
-            source_timezone: revision.wireRevision.period?.source_timezone ?? null,
+            period_start: revision.wireRevision.period.start,
+            period_end: revision.wireRevision.period.end,
+            source_timezone: revision.wireRevision.period.source_timezone,
             observed_at: revision.observedAt,
             data_through: revision.dataThrough,
             revision_content_sha256: revision.binding.sha256,
@@ -509,20 +519,16 @@ SELECT row_data.*
   ) AS current_revision
  USING (reporting_obligation_id, reporting_revision_id);`.trim();
 }
-function sourceLocalDate(start, timeZone) {
-  if (!start) return null;
-  const instant = new Date(start);
-  if (Number.isNaN(instant.getTime())) return null;
+function periodDateOf(revision) {
+  const period = revision.wireRevision.period;
   try {
-    const parts = new Intl.DateTimeFormat("en-CA", {
-      timeZone: timeZone ?? "UTC",
-      year: "numeric",
-      month: "2-digit",
-      day: "2-digit"
-    }).format(instant);
-    return parts;
-  } catch {
-    return instant.toISOString().slice(0, 10);
+    if (!period) throw new TypeError("the revision carries no period");
+    return reportingPeriodDate(period.start, period.source_timezone);
+  } catch (error) {
+    throw new Error(
+      `Cannot compute period_date for revision ${revision.reporting_revision_id}: ${error instanceof Error ? error.message : String(error)}. The batch stays retained and every run fails until the revision's period is repaired (or, if this runtime's timezone data is older than the writer's, until it is upgraded); reset({ discardRetainedPlan: true }) restarts from the beginning, so empty the destination tables first.`,
+      { cause: error }
+    );
   }
 }
 async function withinDeadline(operation, milliseconds, signal, context) {

package/dist/lib/reporting/gcs/adapter.d.mts

@@ -5,6 +5,9 @@ import type { ReportingLedgerStore } from '../ledger/types.mjs';
 import { type ReportingObjectWriteAuthorityStoreV1 } from '../ledger/object-writes.mjs';
 import { type GcsReportingReaderOptionsV1 } from './reader.mjs';
 type DeliveryInput = Parameters<ReportingManagedDeliveryAdapterV1['deliver']>[0];
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export interface CreateGcsReportingManagedDeliveryAdapterOptionsV1 {
     storage: Storage;
     coreStore: ReportingLedgerStore;
@@ -24,7 +27,11 @@ export interface CreateGcsReportingManagedDeliveryAdapterOptionsV1 {
     operationDeadlineMilliseconds?: number;
     minimumResourceRetentionDays?: number;
 }
-/** Complete file-transfer adapter. Availability and cleanup lease commits remain with the managed runtime. */
+/**
+ * Complete file-transfer adapter. Availability and cleanup lease commits remain with the managed runtime.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare function createGcsReportingManagedDeliveryAdapterV1(options: CreateGcsReportingManagedDeliveryAdapterOptionsV1, context?: {
     signal?: AbortSignal;
 }): Promise<ReportingManagedDeliveryAdapterV1>;

package/dist/lib/reporting/gcs/adapter.d.ts

@@ -5,6 +5,9 @@ import type { ReportingLedgerStore } from '../ledger/types';
 import { type ReportingObjectWriteAuthorityStoreV1 } from '../ledger/object-writes';
 import { type GcsReportingReaderOptionsV1 } from './reader';
 type DeliveryInput = Parameters<ReportingManagedDeliveryAdapterV1['deliver']>[0];
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export interface CreateGcsReportingManagedDeliveryAdapterOptionsV1 {
     storage: Storage;
     coreStore: ReportingLedgerStore;
@@ -24,7 +27,11 @@ export interface CreateGcsReportingManagedDeliveryAdapterOptionsV1 {
     operationDeadlineMilliseconds?: number;
     minimumResourceRetentionDays?: number;
 }
-/** Complete file-transfer adapter. Availability and cleanup lease commits remain with the managed runtime. */
+/**
+ * Complete file-transfer adapter. Availability and cleanup lease commits remain with the managed runtime.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare function createGcsReportingManagedDeliveryAdapterV1(options: CreateGcsReportingManagedDeliveryAdapterOptionsV1, context?: {
     signal?: AbortSignal;
 }): Promise<ReportingManagedDeliveryAdapterV1>;

package/dist/lib/reporting/gcs/errors.d.mts

@@ -1,5 +1,11 @@
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare class ReportingGcsFenceError extends Error {
     readonly code: 'INVALID_INPUT' | 'UNSAFE_BUCKET' | 'REVOKED' | 'NOT_REVOKED' | 'CONTENT_CONFLICT' | 'ABORTED' | 'PROVIDER_UNAVAILABLE' | 'DEADLINE_EXCEEDED' | 'HOST_CALLBACK_FAILED' | 'STATE_UNAVAILABLE';
     constructor(code: 'INVALID_INPUT' | 'UNSAFE_BUCKET' | 'REVOKED' | 'NOT_REVOKED' | 'CONTENT_CONFLICT' | 'ABORTED' | 'PROVIDER_UNAVAILABLE' | 'DEADLINE_EXCEEDED' | 'HOST_CALLBACK_FAILED' | 'STATE_UNAVAILABLE');
 }
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare function isReportingGcsFenceError(error: unknown): error is ReportingGcsFenceError;

package/dist/lib/reporting/gcs/errors.d.ts

@@ -1,5 +1,11 @@
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare class ReportingGcsFenceError extends Error {
     readonly code: 'INVALID_INPUT' | 'UNSAFE_BUCKET' | 'REVOKED' | 'NOT_REVOKED' | 'CONTENT_CONFLICT' | 'ABORTED' | 'PROVIDER_UNAVAILABLE' | 'DEADLINE_EXCEEDED' | 'HOST_CALLBACK_FAILED' | 'STATE_UNAVAILABLE';
     constructor(code: 'INVALID_INPUT' | 'UNSAFE_BUCKET' | 'REVOKED' | 'NOT_REVOKED' | 'CONTENT_CONFLICT' | 'ABORTED' | 'PROVIDER_UNAVAILABLE' | 'DEADLINE_EXCEEDED' | 'HOST_CALLBACK_FAILED' | 'STATE_UNAVAILABLE');
 }
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare function isReportingGcsFenceError(error: unknown): error is ReportingGcsFenceError;

package/dist/lib/reporting/gcs/fence.d.mts

@@ -1,6 +1,9 @@
 import type { Storage } from '@google-cloud/storage';
 import { type ReportingObjectWriteScopeV1, type ReportingObjectWritePlanV1, type ReportingObjectWriteStoreV1 } from '../ledger/object-writes.mjs';
 export { ReportingGcsFenceError } from './errors.mjs';
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export interface GcsReportingObjectFenceV1 {
     probe(context?: {
         signal?: AbortSignal;
@@ -25,6 +28,8 @@ export interface GcsReportingObjectFenceV1 {
  * Bucket configuration must remain managed exclusively by the trusted host.
  * Tombstones and inventory MUST NOT be deleted while stale requests can execute.
  * Inject the official Storage client with host-owned, keyless credentials.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
  */
 export declare function createGcsReportingObjectFenceV1(options: {
     storage: Storage;

package/dist/lib/reporting/gcs/fence.d.ts

@@ -1,6 +1,9 @@
 import type { Storage } from '@google-cloud/storage';
 import { type ReportingObjectWriteScopeV1, type ReportingObjectWritePlanV1, type ReportingObjectWriteStoreV1 } from '../ledger/object-writes';
 export { ReportingGcsFenceError } from './errors';
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export interface GcsReportingObjectFenceV1 {
     probe(context?: {
         signal?: AbortSignal;
@@ -25,6 +28,8 @@ export interface GcsReportingObjectFenceV1 {
  * Bucket configuration must remain managed exclusively by the trusted host.
  * Tombstones and inventory MUST NOT be deleted while stale requests can execute.
  * Inject the official Storage client with host-owned, keyless credentials.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
  */
 export declare function createGcsReportingObjectFenceV1(options: {
     storage: Storage;

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

@@ -1,3 +1,12 @@
+/**
+ * Google Cloud Storage fence, reader, managed-delivery adapter and row-object provider for Reliable Reporting.
+ *
+ * Every export of this subpath is `@experimental` and may change in minor releases.
+ *
+ * Stability policy: https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ *
+ * @packageDocumentation
+ */
 export { createGcsReportingObjectFenceV1 } from './fence.mjs';
 export type { GcsReportingObjectFenceV1 } from './fence.mjs';
 export { ReportingGcsFenceError, isReportingGcsFenceError } from './errors.mjs';

package/dist/lib/reporting/gcs/index.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Google Cloud Storage fence, reader, managed-delivery adapter and row-object provider for Reliable Reporting.
+ *
+ * Every export of this subpath is `@experimental` and may change in minor releases.
+ *
+ * Stability policy: https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ *
+ * @packageDocumentation
+ */
 export { createGcsReportingObjectFenceV1 } from './fence';
 export type { GcsReportingObjectFenceV1 } from './fence';
 export { ReportingGcsFenceError, isReportingGcsFenceError } from './errors';

package/dist/lib/reporting/gcs/reader.d.mts

@@ -2,16 +2,25 @@ import type { Storage } from '@google-cloud/storage';
 import { type CanonicalReferenceResolver } from '../../canonical-references/index.mjs';
 import type { ReportingResourceReader } from '../inspection.mjs';
 import { type ReportingObjectWriteScopeV1 } from '../ledger/object-writes.mjs';
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export interface GcsReportingReadScopeV1 extends ReportingObjectWriteScopeV1 {
     /** Non-secret identity from the host's authenticated principal registry. Never a bearer. */
     principal_id: string;
 }
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export interface GcsReportingReadAuthorizationV1 {
     scope: Readonly<GcsReportingReadScopeV1>;
     bucket: string;
     objectPrefix: string;
     objectName: string;
 }
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export interface GcsReportingReaderOptionsV1 {
     scope: GcsReportingReadScopeV1;
     bucket: string;
@@ -30,14 +39,29 @@ export interface GcsReportingReaderOptionsV1 {
     operationDeadlineMilliseconds?: number;
     maxBytes?: number;
 }
-/** Restrictive provider-native URL grammar: no credentials, queries, encoding or traversal. */
+/**
+ * Restrictive provider-native URL grammar: no credentials, queries, encoding or traversal.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare function gcsReportingObjectFromUriV1(uri: string, bucket: string, prefix: string): string;
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare function createGcsScopedObjectReadV1(options: GcsReportingReaderOptionsV1): (uri: string, maxBytes: number, signal?: AbortSignal, nativeVersion?: string) => Promise<{
     body: Buffer<ArrayBufferLike>;
     contentType: string | undefined;
     generation: string;
 }>;
-/** Destination-bound manifest/object reader. The caller never supplies bucket or credential scope. */
+/**
+ * Destination-bound manifest/object reader. The caller never supplies bucket or credential scope.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare function createGcsReportingResourceReaderV1(options: GcsReportingReaderOptionsV1): ReportingResourceReader;
-/** Digest-pinned private contract resolver; all resolutions re-authorize and bypass caches. */
+/**
+ * Digest-pinned private contract resolver; all resolutions re-authorize and bypass caches.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare function createGcsReportingReferenceResolverV1(options: GcsReportingReaderOptionsV1): CanonicalReferenceResolver;

package/dist/lib/reporting/gcs/reader.d.ts

@@ -2,16 +2,25 @@ import type { Storage } from '@google-cloud/storage';
 import { type CanonicalReferenceResolver } from '../../canonical-references';
 import type { ReportingResourceReader } from '../inspection';
 import { type ReportingObjectWriteScopeV1 } from '../ledger/object-writes';
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export interface GcsReportingReadScopeV1 extends ReportingObjectWriteScopeV1 {
     /** Non-secret identity from the host's authenticated principal registry. Never a bearer. */
     principal_id: string;
 }
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export interface GcsReportingReadAuthorizationV1 {
     scope: Readonly<GcsReportingReadScopeV1>;
     bucket: string;
     objectPrefix: string;
     objectName: string;
 }
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export interface GcsReportingReaderOptionsV1 {
     scope: GcsReportingReadScopeV1;
     bucket: string;
@@ -30,14 +39,29 @@ export interface GcsReportingReaderOptionsV1 {
     operationDeadlineMilliseconds?: number;
     maxBytes?: number;
 }
-/** Restrictive provider-native URL grammar: no credentials, queries, encoding or traversal. */
+/**
+ * Restrictive provider-native URL grammar: no credentials, queries, encoding or traversal.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare function gcsReportingObjectFromUriV1(uri: string, bucket: string, prefix: string): string;
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare function createGcsScopedObjectReadV1(options: GcsReportingReaderOptionsV1): (uri: string, maxBytes: number, signal?: AbortSignal, nativeVersion?: string) => Promise<{
     body: Buffer<ArrayBufferLike>;
     contentType: string | undefined;
     generation: string;
 }>;
-/** Destination-bound manifest/object reader. The caller never supplies bucket or credential scope. */
+/**
+ * Destination-bound manifest/object reader. The caller never supplies bucket or credential scope.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare function createGcsReportingResourceReaderV1(options: GcsReportingReaderOptionsV1): ReportingResourceReader;
-/** Digest-pinned private contract resolver; all resolutions re-authorize and bypass caches. */
+/**
+ * Digest-pinned private contract resolver; all resolutions re-authorize and bypass caches.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export declare function createGcsReportingReferenceResolverV1(options: GcsReportingReaderOptionsV1): CanonicalReferenceResolver;

package/dist/lib/reporting/gcs/row-provider.d.mts

@@ -1,5 +1,8 @@
 import type { BucketMetadata, Storage } from '@google-cloud/storage';
 import type { ReportingRowObjectProviderV1 } from '../ledger/row-storage-object.mjs';
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export interface CreateGcsReportingRowObjectProviderOptionsV1 {
     /** Official client used by bindings without a `credentialRef`. */
     storage?: Storage;
@@ -16,6 +19,8 @@ export interface CreateGcsReportingRowObjectProviderOptionsV1 {
  * public access prevention, and any lifecycle `Delete` rule that can match a
  * live object under the binding prefix (no prefix filter, or a prefix that
  * overlaps it). Rules limited to noncurrent versions are allowed.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
  */
 export declare function assertGcsReportingRowBucketPolicyV1(metadata: BucketMetadata, prefix: string): void;
 /**
@@ -28,5 +33,7 @@ export declare function assertGcsReportingRowBucketPolicyV1(metadata: BucketMeta
  * object generation, and reads and deletes pin it. Objects are stored without
  * `Content-Encoding`, and reads request raw stored bytes, so GCS never
  * transcodes them.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
  */
 export declare function createGcsReportingRowObjectProviderV1(options: CreateGcsReportingRowObjectProviderOptionsV1): ReportingRowObjectProviderV1;

package/dist/lib/reporting/gcs/row-provider.d.ts

@@ -1,5 +1,8 @@
 import type { BucketMetadata, Storage } from '@google-cloud/storage';
 import type { ReportingRowObjectProviderV1 } from '../ledger/row-storage-object';
+/**
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ */
 export interface CreateGcsReportingRowObjectProviderOptionsV1 {
     /** Official client used by bindings without a `credentialRef`. */
     storage?: Storage;
@@ -16,6 +19,8 @@ export interface CreateGcsReportingRowObjectProviderOptionsV1 {
  * public access prevention, and any lifecycle `Delete` rule that can match a
  * live object under the binding prefix (no prefix filter, or a prefix that
  * overlaps it). Rules limited to noncurrent versions are allowed.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
  */
 export declare function assertGcsReportingRowBucketPolicyV1(metadata: BucketMetadata, prefix: string): void;
 /**
@@ -28,5 +33,7 @@ export declare function assertGcsReportingRowBucketPolicyV1(metadata: BucketMeta
  * object generation, and reads and deletes pin it. Objects are stored without
  * `Content-Encoding`, and reads request raw stored bytes, so GCS never
  * transcodes them.
+ *
+ * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
  */
 export declare function createGcsReportingRowObjectProviderV1(options: CreateGcsReportingRowObjectProviderOptionsV1): ReportingRowObjectProviderV1;