@adcp/sdk 15.9.0 → 16.0.0-beta.1

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

@@ -199,6 +199,9 @@ export interface ReportingLedgerAdjustmentV1 {
 export type ReportingLedgerRevisionSnapshotV1 = Omit<ReportingLedgerRevisionV1, 'rows'>;
 export type ReportingLedgerRevisionMetadataV1 = Omit<ReportingLedgerRevisionV1, 'rows'>;
 export type ReportingLedgerAdjustmentMetadataV1 = Omit<ReportingLedgerAdjustmentV1, 'rows'>;
+/**
+ * @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 ReportingRevisionRowsReadV1 {
     reporting_revision_id: string;
     account_id: string;
@@ -208,6 +211,9 @@ export interface ReportingRevisionRowsReadV1 {
     limit: number;
     signal?: AbortSignal;
 }
+/**
+ * @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 ReportingRevisionRowsPageV1 {
     rows: Record<string, unknown>[];
     /** Total rows in the revision. */
@@ -434,7 +440,11 @@ export interface ReportingLedgerStatusTransitionV1 {
     occurredAt: string;
     notifiedAt?: string;
 }
-/** Minimum transaction surface used by the bundled PostgreSQL ledger. */
+/**
+ * Minimum transaction surface used by the bundled PostgreSQL ledger.
+ *
+ * @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 ReportingLedgerTransactionV1 {
     query<Row extends Record<string, unknown> = Record<string, unknown>>(text: string, values?: unknown[]): Promise<{
         rows: Row[];
@@ -559,6 +569,8 @@ export interface ReportingLedgerPageV1 {
  * Immutable opt-in binding between one Core configuration generation and one
  * caller-owned destination authorization generation. Core configurations do
  * not carry this shape and remain API-delivered.
+ *
+ * @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 ReportingManagedDeliveryBindingV1 {
     configurationId: string;
@@ -701,6 +713,9 @@ export interface ReportingManagedLifecycleProjectionV1 {
      */
     obligatedConsumerRosterVersion?: 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 ReportingLedgerLeaseV1 {
     obligation: ReportingLedgerObligationV1;
     owner: string;
@@ -717,6 +732,9 @@ export declare class ReportingConsumerStatusConflictError extends Error {
      */
     constructor(message?: 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 ReportingLedgerStore {
     /** Optional substrate identity for an add-on store that must prove shared authority. */
     readonly [REPORTING_LEDGER_AUTHORITY]?: ReportingLedgerAuthorityV1;
@@ -961,6 +979,8 @@ export interface ReportingLedgerStore {
  * in duplicate-ID or duplicate-logical-chain groups, then atomically compare
  * the current leaf, append, and retain the original ordered batch result for
  * idempotent replay.
+ *
+ * @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 ReportingConsumerStatusLedgerStore {
     listConfigurations(account_id: string): Promise<ReportingLedgerConfigurationV1[]>;
@@ -1034,6 +1054,8 @@ export type ReportingDeliveryHandlerV1 = (request: AdcpToolMap['get_media_buy_de
  * belongs to it, so the reader MUST scope the lookup by that account and return
  * `null` for a revision that belongs to another one. Never return a response
  * for a revision the resolved account cannot read.
+ *
+ * @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 type ReportingLegacyRevisionReaderV1 = (request: AdcpToolMap['get_media_buy_delivery']['params'], context: HandlerContext<unknown>) => Promise<AdcpToolMap['get_media_buy_delivery']['result'] | null | undefined>;
 export interface CreateReportingDeliveryHandlerOptionsV1 {

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

@@ -199,6 +199,9 @@ export interface ReportingLedgerAdjustmentV1 {
 export type ReportingLedgerRevisionSnapshotV1 = Omit<ReportingLedgerRevisionV1, 'rows'>;
 export type ReportingLedgerRevisionMetadataV1 = Omit<ReportingLedgerRevisionV1, 'rows'>;
 export type ReportingLedgerAdjustmentMetadataV1 = Omit<ReportingLedgerAdjustmentV1, 'rows'>;
+/**
+ * @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 ReportingRevisionRowsReadV1 {
     reporting_revision_id: string;
     account_id: string;
@@ -208,6 +211,9 @@ export interface ReportingRevisionRowsReadV1 {
     limit: number;
     signal?: AbortSignal;
 }
+/**
+ * @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 ReportingRevisionRowsPageV1 {
     rows: Record<string, unknown>[];
     /** Total rows in the revision. */
@@ -434,7 +440,11 @@ export interface ReportingLedgerStatusTransitionV1 {
     occurredAt: string;
     notifiedAt?: string;
 }
-/** Minimum transaction surface used by the bundled PostgreSQL ledger. */
+/**
+ * Minimum transaction surface used by the bundled PostgreSQL ledger.
+ *
+ * @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 ReportingLedgerTransactionV1 {
     query<Row extends Record<string, unknown> = Record<string, unknown>>(text: string, values?: unknown[]): Promise<{
         rows: Row[];
@@ -559,6 +569,8 @@ export interface ReportingLedgerPageV1 {
  * Immutable opt-in binding between one Core configuration generation and one
  * caller-owned destination authorization generation. Core configurations do
  * not carry this shape and remain API-delivered.
+ *
+ * @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 ReportingManagedDeliveryBindingV1 {
     configurationId: string;
@@ -701,6 +713,9 @@ export interface ReportingManagedLifecycleProjectionV1 {
      */
     obligatedConsumerRosterVersion?: 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 ReportingLedgerLeaseV1 {
     obligation: ReportingLedgerObligationV1;
     owner: string;
@@ -717,6 +732,9 @@ export declare class ReportingConsumerStatusConflictError extends Error {
      */
     constructor(message?: 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 ReportingLedgerStore {
     /** Optional substrate identity for an add-on store that must prove shared authority. */
     readonly [REPORTING_LEDGER_AUTHORITY]?: ReportingLedgerAuthorityV1;
@@ -961,6 +979,8 @@ export interface ReportingLedgerStore {
  * in duplicate-ID or duplicate-logical-chain groups, then atomically compare
  * the current leaf, append, and retain the original ordered batch result for
  * idempotent replay.
+ *
+ * @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 ReportingConsumerStatusLedgerStore {
     listConfigurations(account_id: string): Promise<ReportingLedgerConfigurationV1[]>;
@@ -1034,6 +1054,8 @@ export type ReportingDeliveryHandlerV1 = (request: AdcpToolMap['get_media_buy_de
  * belongs to it, so the reader MUST scope the lookup by that account and return
  * `null` for a revision that belongs to another one. Never return a response
  * for a revision the resolved account cannot read.
+ *
+ * @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 type ReportingLegacyRevisionReaderV1 = (request: AdcpToolMap['get_media_buy_delivery']['params'], context: HandlerContext<unknown>) => Promise<AdcpToolMap['get_media_buy_delivery']['result'] | null | undefined>;
 export interface CreateReportingDeliveryHandlerOptionsV1 {

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

@@ -1,5 +1,8 @@
 import { type S3Client } from '@aws-sdk/client-s3';
 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 CreateS3ReportingRowObjectProviderOptionsV1 {
     /** Official client used by bindings without a `credentialRef`. */
     client?: S3Client;
@@ -25,5 +28,7 @@ export interface CreateS3ReportingRowObjectProviderOptionsV1 {
  * and cannot fence that). The probe refuses unversioned or suspended buckets.
  * Because S3-compatible stores may silently ignore `If-None-Match`, the probe
  * also proves create-only behaviour empirically before any binding is used.
+ *
+ * @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 createS3ReportingRowObjectProviderV1(options: CreateS3ReportingRowObjectProviderOptionsV1): ReportingRowObjectProviderV1;

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

@@ -1,5 +1,8 @@
 import { type S3Client } from '@aws-sdk/client-s3';
 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 CreateS3ReportingRowObjectProviderOptionsV1 {
     /** Official client used by bindings without a `credentialRef`. */
     client?: S3Client;
@@ -25,5 +28,7 @@ export interface CreateS3ReportingRowObjectProviderOptionsV1 {
  * and cannot fence that). The probe refuses unversioned or suspended buckets.
  * Because S3-compatible stores may silently ignore `If-None-Match`, the probe
  * also proves create-only behaviour empirically before any binding is used.
+ *
+ * @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 createS3ReportingRowObjectProviderV1(options: CreateS3ReportingRowObjectProviderOptionsV1): ReportingRowObjectProviderV1;

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

@@ -52,9 +52,9 @@ function versionOf(output) {
   }
   return id;
 }
-function selectorOf(nativeVersion) {
-  if (typeof nativeVersion !== "string" || nativeVersion === "null") return null;
-  return VERSION_ID.test(nativeVersion) ? { VersionId: nativeVersion } : null;
+function selectorOf(nativeVersionRef) {
+  if (typeof nativeVersionRef !== "string" || nativeVersionRef === "null") return null;
+  return VERSION_ID.test(nativeVersionRef) ? { VersionId: nativeVersionRef } : null;
 }
 function servedVersion(output, selector) {
   return output.VersionId === selector.VersionId;
@@ -217,14 +217,14 @@ function createS3ReportingRowObjectProviderV1(options) {
     putIfAbsent(input, context) {
       return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
         const { client, Bucket } = target(input);
-        assertKey(input.key);
+        assertKey(input.objectRef);
         const bytes = Buffer.from(input.bytes);
         try {
           const output = await putCreateOnly(
             client,
             {
               Bucket,
-              Key: input.key,
+              Key: input.objectRef,
               Body: bytes,
               ContentLength: bytes.byteLength,
               ContentType: input.contentType,
@@ -233,24 +233,24 @@ function createS3ReportingRowObjectProviderV1(options) {
             },
             context.signal
           );
-          return { created: true, nativeVersion: versionOf(output) };
+          return { created: true, nativeVersionRef: versionOf(output) };
         } catch (error) {
           if (!isPreconditionFailed(error)) throw error;
         }
-        const head = await client.send(new import_client_s3.HeadObjectCommand({ Bucket, Key: input.key }), {
+        const head = await client.send(new import_client_s3.HeadObjectCommand({ Bucket, Key: input.objectRef }), {
           abortSignal: context.signal
         });
-        return { created: false, nativeVersion: versionOf(head) };
+        return { created: false, nativeVersionRef: versionOf(head) };
       });
     },
     get(input, context) {
       return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
         const { client, Bucket } = target(input);
-        assertKey(input.key);
+        assertKey(input.objectRef);
         (0, import_row_storage_provider_io.assertReportingRowReadBounds)(input);
-        const selector = selectorOf(input.nativeVersion);
+        const selector = selectorOf(input.nativeVersionRef);
         if (selector === null) return null;
-        const Key = input.key;
+        const Key = input.objectRef;
         try {
           if (input.range?.length === 0) {
             const head = await client.send(new import_client_s3.HeadObjectCommand({ Bucket, Key, ...selector }), {
@@ -294,13 +294,36 @@ function createS3ReportingRowObjectProviderV1(options) {
         }
       });
     },
+    stat(input, context) {
+      return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
+        const { client, Bucket } = target(input);
+        assertKey(input.objectRef);
+        const selector = selectorOf(input.nativeVersionRef);
+        if (selector === null) return null;
+        try {
+          const head = await client.send(new import_client_s3.HeadObjectCommand({ Bucket, Key: input.objectRef, ...selector }), {
+            abortSignal: context.signal
+          });
+          if (!servedVersion(head, selector)) return null;
+          const size = head.ContentLength;
+          if (typeof size !== "number" || !Number.isSafeInteger(size) || size < 0) {
+            throw new import_row_storage_errors.ReportingRowStoreError("PROVIDER_UNAVAILABLE", "object metadata is malformed");
+          }
+          return { nativeVersionRef: selector.VersionId, sizeBytes: size };
+        } catch (error) {
+          if (isNotFound(error) || isPreconditionFailed(error)) return null;
+          if (statusOf(error) === 400 || statusOf(error) === 405) return null;
+          throw error;
+        }
+      });
+    },
     delete(input, context) {
       return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
         const { client, Bucket } = target(input);
-        assertKey(input.key);
-        const selector = selectorOf(input.nativeVersion);
+        assertKey(input.objectRef);
+        const selector = selectorOf(input.nativeVersionRef);
         if (selector === null) return "absent";
-        const Key = input.key;
+        const Key = input.objectRef;
         const signal = context.signal;
         try {
           const head = await client.send(new import_client_s3.HeadObjectCommand({ Bucket, Key, ...selector }), { abortSignal: signal });

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

@@ -46,9 +46,9 @@ function versionOf(output) {
   }
   return id;
 }
-function selectorOf(nativeVersion) {
-  if (typeof nativeVersion !== "string" || nativeVersion === "null") return null;
-  return VERSION_ID.test(nativeVersion) ? { VersionId: nativeVersion } : null;
+function selectorOf(nativeVersionRef) {
+  if (typeof nativeVersionRef !== "string" || nativeVersionRef === "null") return null;
+  return VERSION_ID.test(nativeVersionRef) ? { VersionId: nativeVersionRef } : null;
 }
 function servedVersion(output, selector) {
   return output.VersionId === selector.VersionId;
@@ -211,14 +211,14 @@ function createS3ReportingRowObjectProviderV1(options) {
     putIfAbsent(input, context) {
       return runReportingRowProviderOperation(context.signal, async () => {
         const { client, Bucket } = target(input);
-        assertKey(input.key);
+        assertKey(input.objectRef);
         const bytes = Buffer.from(input.bytes);
         try {
           const output = await putCreateOnly(
             client,
             {
               Bucket,
-              Key: input.key,
+              Key: input.objectRef,
               Body: bytes,
               ContentLength: bytes.byteLength,
               ContentType: input.contentType,
@@ -227,24 +227,24 @@ function createS3ReportingRowObjectProviderV1(options) {
             },
             context.signal
           );
-          return { created: true, nativeVersion: versionOf(output) };
+          return { created: true, nativeVersionRef: versionOf(output) };
         } catch (error) {
           if (!isPreconditionFailed(error)) throw error;
         }
-        const head = await client.send(new HeadObjectCommand({ Bucket, Key: input.key }), {
+        const head = await client.send(new HeadObjectCommand({ Bucket, Key: input.objectRef }), {
           abortSignal: context.signal
         });
-        return { created: false, nativeVersion: versionOf(head) };
+        return { created: false, nativeVersionRef: versionOf(head) };
       });
     },
     get(input, context) {
       return runReportingRowProviderOperation(context.signal, async () => {
         const { client, Bucket } = target(input);
-        assertKey(input.key);
+        assertKey(input.objectRef);
         assertReportingRowReadBounds(input);
-        const selector = selectorOf(input.nativeVersion);
+        const selector = selectorOf(input.nativeVersionRef);
         if (selector === null) return null;
-        const Key = input.key;
+        const Key = input.objectRef;
         try {
           if (input.range?.length === 0) {
             const head = await client.send(new HeadObjectCommand({ Bucket, Key, ...selector }), {
@@ -288,13 +288,36 @@ function createS3ReportingRowObjectProviderV1(options) {
         }
       });
     },
+    stat(input, context) {
+      return runReportingRowProviderOperation(context.signal, async () => {
+        const { client, Bucket } = target(input);
+        assertKey(input.objectRef);
+        const selector = selectorOf(input.nativeVersionRef);
+        if (selector === null) return null;
+        try {
+          const head = await client.send(new HeadObjectCommand({ Bucket, Key: input.objectRef, ...selector }), {
+            abortSignal: context.signal
+          });
+          if (!servedVersion(head, selector)) return null;
+          const size = head.ContentLength;
+          if (typeof size !== "number" || !Number.isSafeInteger(size) || size < 0) {
+            throw new ReportingRowStoreError("PROVIDER_UNAVAILABLE", "object metadata is malformed");
+          }
+          return { nativeVersionRef: selector.VersionId, sizeBytes: size };
+        } catch (error) {
+          if (isNotFound(error) || isPreconditionFailed(error)) return null;
+          if (statusOf(error) === 400 || statusOf(error) === 405) return null;
+          throw error;
+        }
+      });
+    },
     delete(input, context) {
       return runReportingRowProviderOperation(context.signal, async () => {
         const { client, Bucket } = target(input);
-        assertKey(input.key);
-        const selector = selectorOf(input.nativeVersion);
+        assertKey(input.objectRef);
+        const selector = selectorOf(input.nativeVersionRef);
         if (selector === null) return "absent";
-        const Key = input.key;
+        const Key = input.objectRef;
         const signal = context.signal;
         try {
           const head = await client.send(new HeadObjectCommand({ Bucket, Key, ...selector }), { abortSignal: signal });

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

@@ -1,3 +1,13 @@
+/**
+ * Reliable Reporting service wiring, conformance runner and ledger maintenance.
+ *
+ * Only the retention, compaction and change-feed maintenance exports (`./maintenance`) are `@experimental`.
+ * The service factories and conformance runner follow normal semver.
+ *
+ * Stability policy: https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ *
+ * @packageDocumentation
+ */
 import type { Account, ResolveContext } from '../../server/decisioning/account.mjs';
 import type { RequestContext } from '../../server/decisioning/context.mjs';
 import type { DecisioningPlatform } from '../../server/decisioning/platform.mjs';

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

@@ -1,3 +1,13 @@
+/**
+ * Reliable Reporting service wiring, conformance runner and ledger maintenance.
+ *
+ * Only the retention, compaction and change-feed maintenance exports (`./maintenance`) are `@experimental`.
+ * The service factories and conformance runner follow normal semver.
+ *
+ * Stability policy: https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ *
+ * @packageDocumentation
+ */
 import type { Account, ResolveContext } from '../../server/decisioning/account';
 import type { RequestContext } from '../../server/decisioning/context';
 import type { DecisioningPlatform } from '../../server/decisioning/platform';

package/dist/lib/reporting/service/maintenance.d.mts

@@ -5,6 +5,8 @@ import type { PostgresReportingLedgerStore } from '../ledger/index.mjs';
  * period end and its latest publication. `statusRetentionDays` always comes
  * from the service, so retention can never disagree with the commitment the
  * service advertises to buyers.
+ *
+ * @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 ReportingRetentionOptionsV1 {
     enabled: true;
@@ -19,18 +21,28 @@ export interface ReportingRetentionOptionsV1 {
  *
  * Compaction takes effect in the AdCP release after November 20, 2026; do not
  * enable it in production before then. See `docs/guides/REPORTING-OPERATIONS.md`.
+ *
+ * @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 ReportingCompactionOptionsV1 {
     enabled: true;
     /** Revisions compacted per pass. Defaults to 100. */
     limit?: number;
 }
-/** Change-feed pruning window and the consumer hold shared with retention. */
+/**
+ * Change-feed pruning window and the consumer hold shared with retention.
+ *
+ * @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 type ReportingChangeFeedMaintenanceOptionsV1 = boolean | {
     changeRetentionDays?: number;
     maxFeedHoldDays?: number;
 };
-/** The ledger-store surface a maintenance pass drives. */
+/**
+ * The ledger-store surface a maintenance pass drives.
+ *
+ * @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 type ReportingLedgerMaintenanceStoreV1 = Pick<PostgresReportingLedgerStore, 'sweepRowWriteIntents' | 'pruneChanges' | 'retireExpiredPeriods'> & Partial<Pick<PostgresReportingLedgerStore, 'compactSupersededSnapshots'>>;
 interface ReportingLedgerMaintenanceTaskOutcomesV1 {
     'snapshot sweep': Awaited<ReturnType<PostgresReportingLedgerStore['sweepExpiredState']>>;
@@ -39,11 +51,16 @@ interface ReportingLedgerMaintenanceTaskOutcomesV1 {
     retention: Awaited<ReturnType<PostgresReportingLedgerStore['retireExpiredPeriods']>>;
     'snapshot compaction': Awaited<ReturnType<PostgresReportingLedgerStore['compactSupersededSnapshots']>>;
 }
+/**
+ * @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 type ReportingLedgerMaintenanceTaskNameV1 = keyof ReportingLedgerMaintenanceTaskOutcomesV1;
 /**
  * A scheduled maintenance pass completed but could not process some items
  * (for example, a retention period whose objects could not be deleted). The
  * pass resumes them next time; repeated reports need operator attention.
+ *
+ * @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 ReportingMaintenancePartialFailureError extends Error {
     readonly task: string;
@@ -68,6 +85,8 @@ export declare class ReportingMaintenancePartialFailureError extends Error {
  * some items (a retention period whose objects would not delete, an upload that
  * would not sweep) is `completed` with `partialFailure` set; the pass resumes
  * those items next time.
+ *
+ * @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 type ReportingLedgerMaintenanceTaskResultV1 = {
     [Task in ReportingLedgerMaintenanceTaskNameV1]: {
@@ -81,6 +100,9 @@ export type ReportingLedgerMaintenanceTaskResultV1 = {
         readonly error: unknown;
     };
 }[ReportingLedgerMaintenanceTaskNameV1];
+/**
+ * @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 RunReportingLedgerMaintenanceInputV1 {
     store: ReportingLedgerMaintenanceStoreV1;
     /**
@@ -108,11 +130,15 @@ export interface RunReportingLedgerMaintenanceInputV1 {
  * retention honours, per-task limits and abort handling cannot drift between
  * them. Tasks start together, in a fixed order, and are isolated: one task's
  * failure never prevents another from running.
+ *
+ * @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 runReportingLedgerMaintenance(input: RunReportingLedgerMaintenanceInputV1): Promise<ReportingLedgerMaintenanceTaskResultV1[]>;
 /**
  * Fail fast on maintenance options the store would otherwise reject on every
  * pass. Mirrors the checks `retireExpiredPeriods` and `pruneChanges` apply.
+ *
+ * @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 assertReportingLedgerMaintenanceOptions(input: {
     retention?: ReportingRetentionOptionsV1 | undefined;

package/dist/lib/reporting/service/maintenance.d.ts

@@ -5,6 +5,8 @@ import type { PostgresReportingLedgerStore } from '../ledger';
  * period end and its latest publication. `statusRetentionDays` always comes
  * from the service, so retention can never disagree with the commitment the
  * service advertises to buyers.
+ *
+ * @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 ReportingRetentionOptionsV1 {
     enabled: true;
@@ -19,18 +21,28 @@ export interface ReportingRetentionOptionsV1 {
  *
  * Compaction takes effect in the AdCP release after November 20, 2026; do not
  * enable it in production before then. See `docs/guides/REPORTING-OPERATIONS.md`.
+ *
+ * @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 ReportingCompactionOptionsV1 {
     enabled: true;
     /** Revisions compacted per pass. Defaults to 100. */
     limit?: number;
 }
-/** Change-feed pruning window and the consumer hold shared with retention. */
+/**
+ * Change-feed pruning window and the consumer hold shared with retention.
+ *
+ * @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 type ReportingChangeFeedMaintenanceOptionsV1 = boolean | {
     changeRetentionDays?: number;
     maxFeedHoldDays?: number;
 };
-/** The ledger-store surface a maintenance pass drives. */
+/**
+ * The ledger-store surface a maintenance pass drives.
+ *
+ * @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 type ReportingLedgerMaintenanceStoreV1 = Pick<PostgresReportingLedgerStore, 'sweepRowWriteIntents' | 'pruneChanges' | 'retireExpiredPeriods'> & Partial<Pick<PostgresReportingLedgerStore, 'compactSupersededSnapshots'>>;
 interface ReportingLedgerMaintenanceTaskOutcomesV1 {
     'snapshot sweep': Awaited<ReturnType<PostgresReportingLedgerStore['sweepExpiredState']>>;
@@ -39,11 +51,16 @@ interface ReportingLedgerMaintenanceTaskOutcomesV1 {
     retention: Awaited<ReturnType<PostgresReportingLedgerStore['retireExpiredPeriods']>>;
     'snapshot compaction': Awaited<ReturnType<PostgresReportingLedgerStore['compactSupersededSnapshots']>>;
 }
+/**
+ * @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 type ReportingLedgerMaintenanceTaskNameV1 = keyof ReportingLedgerMaintenanceTaskOutcomesV1;
 /**
  * A scheduled maintenance pass completed but could not process some items
  * (for example, a retention period whose objects could not be deleted). The
  * pass resumes them next time; repeated reports need operator attention.
+ *
+ * @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 ReportingMaintenancePartialFailureError extends Error {
     readonly task: string;
@@ -68,6 +85,8 @@ export declare class ReportingMaintenancePartialFailureError extends Error {
  * some items (a retention period whose objects would not delete, an upload that
  * would not sweep) is `completed` with `partialFailure` set; the pass resumes
  * those items next time.
+ *
+ * @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 type ReportingLedgerMaintenanceTaskResultV1 = {
     [Task in ReportingLedgerMaintenanceTaskNameV1]: {
@@ -81,6 +100,9 @@ export type ReportingLedgerMaintenanceTaskResultV1 = {
         readonly error: unknown;
     };
 }[ReportingLedgerMaintenanceTaskNameV1];
+/**
+ * @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 RunReportingLedgerMaintenanceInputV1 {
     store: ReportingLedgerMaintenanceStoreV1;
     /**
@@ -108,11 +130,15 @@ export interface RunReportingLedgerMaintenanceInputV1 {
  * retention honours, per-task limits and abort handling cannot drift between
  * them. Tasks start together, in a fixed order, and are isolated: one task's
  * failure never prevents another from running.
+ *
+ * @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 runReportingLedgerMaintenance(input: RunReportingLedgerMaintenanceInputV1): Promise<ReportingLedgerMaintenanceTaskResultV1[]>;
 /**
  * Fail fast on maintenance options the store would otherwise reject on every
  * pass. Mirrors the checks `retireExpiredPeriods` and `pruneChanges` apply.
+ *
+ * @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 assertReportingLedgerMaintenanceOptions(input: {
     retention?: ReportingRetentionOptionsV1 | undefined;

package/dist/lib/schemas-data/v2.5/_provenance.json

@@ -4,5 +4,5 @@
   "source_sha": "4e553ad955f83b49c7d221ab5c3ff78237ad02e3",
   "source_tarball_sha256": "580656d6466ef9f0d1119985e6726c2efea718dc671e2ad30957fcb2fd54af0f",
   "upstream_adcp_version": "2.5.3",
-  "synced_at": "2026-10-13T02:34:34.174Z"
+  "synced_at": "2026-10-14T04:36:25.896Z"
 }

package/dist/lib/server/account-sync-contract.d.mts

@@ -0,0 +1,14 @@
+import type { AdcpLogger } from './create-adcp-server.mjs';
+import { toWireAccount } from './decisioning/account.mjs';
+import type { Account, AccountStore, AccountSyncDiagnostic, ResolveContext, SyncAccountsResultRow } from './decisioning/account.mjs';
+type Entry = Record<string, unknown>;
+/** Copy request input only when a callback reads it; keep auth capabilities live. */
+export declare function isolateAccountCallbackInput(ctx: ResolveContext): ResolveContext;
+export declare function existingSyncAccounts(accounts: AccountStore, entries: Entry[], ctx: ResolveContext, logger?: AdcpLogger): Promise<(Account | null)[]>;
+export declare function diagnoseAccountBilling(accounts: AccountStore, logger: AdcpLogger, account: {
+    billing?: string;
+    payment_terms?: string;
+}, toolName: AccountSyncDiagnostic['toolName'], index: number): void;
+export declare function projectAccountList(accounts: AccountStore, items: Account[], ctx: ResolveContext, logger: AdcpLogger): Promise<ReturnType<typeof toWireAccount>[]>;
+export declare function checkSyncAccountRows(accounts: AccountStore, entries: Entry[], existing: (Account | null)[], rows: SyncAccountsResultRow[], indices: number[], ctx: ResolveContext, logger: AdcpLogger): Promise<SyncAccountsResultRow[]>;
+export {};

package/dist/lib/server/account-sync-contract.d.ts

@@ -0,0 +1,14 @@
+import type { AdcpLogger } from './create-adcp-server';
+import { toWireAccount } from './decisioning/account';
+import type { Account, AccountStore, AccountSyncDiagnostic, ResolveContext, SyncAccountsResultRow } from './decisioning/account';
+type Entry = Record<string, unknown>;
+/** Copy request input only when a callback reads it; keep auth capabilities live. */
+export declare function isolateAccountCallbackInput(ctx: ResolveContext): ResolveContext;
+export declare function existingSyncAccounts(accounts: AccountStore, entries: Entry[], ctx: ResolveContext, logger?: AdcpLogger): Promise<(Account | null)[]>;
+export declare function diagnoseAccountBilling(accounts: AccountStore, logger: AdcpLogger, account: {
+    billing?: string;
+    payment_terms?: string;
+}, toolName: AccountSyncDiagnostic['toolName'], index: number): void;
+export declare function projectAccountList(accounts: AccountStore, items: Account[], ctx: ResolveContext, logger: AdcpLogger): Promise<ReturnType<typeof toWireAccount>[]>;
+export declare function checkSyncAccountRows(accounts: AccountStore, entries: Entry[], existing: (Account | null)[], rows: SyncAccountsResultRow[], indices: number[], ctx: ResolveContext, logger: AdcpLogger): Promise<SyncAccountsResultRow[]>;
+export {};