@adcp/sdk 15.9.1 → 16.0.0-beta.2

package/dist/lib/reporting/gcs/row-provider.js

@@ -40,8 +40,8 @@ function generationOf(metadata) {
   }
   return generation;
 }
-function pinnedGeneration(nativeVersion) {
-  return typeof nativeVersion === "string" && GENERATION.test(nativeVersion) && Number.isSafeInteger(Number(nativeVersion)) ? nativeVersion : null;
+function pinnedGeneration(nativeVersionRef) {
+  return typeof nativeVersionRef === "string" && GENERATION.test(nativeVersionRef) && Number.isSafeInteger(Number(nativeVersionRef)) ? nativeVersionRef : null;
 }
 function assertGcsReportingRowBucketPolicyV1(metadata, prefix) {
   if (!metadata || typeof metadata !== "object") {
@@ -112,8 +112,8 @@ function createGcsReportingRowObjectProviderV1(options) {
     putIfAbsent(input, context) {
       return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
         const bucket = bucketFor(input);
-        assertKey(input.key);
-        const file = bucket.file(input.key);
+        assertKey(input.objectRef);
+        const file = bucket.file(input.objectRef);
         try {
           const bytes = Buffer.from(input.bytes);
           await file.save(bytes, {
@@ -135,24 +135,24 @@ function createGcsReportingRowObjectProviderV1(options) {
         } catch (error) {
           if (status(error) !== 412) throw error;
           context.signal.throwIfAborted();
-          const [existing] = await bucket.file(input.key).getMetadata();
-          return { created: false, nativeVersion: generationOf(existing) };
+          const [existing] = await bucket.file(input.objectRef).getMetadata();
+          return { created: false, nativeVersionRef: generationOf(existing) };
         }
         if (file.metadata?.generation !== void 0) {
-          return { created: true, nativeVersion: generationOf(file.metadata) };
+          return { created: true, nativeVersionRef: generationOf(file.metadata) };
         }
         const [created] = await file.getMetadata();
-        return { created: true, nativeVersion: generationOf(created) };
+        return { created: true, nativeVersionRef: generationOf(created) };
       });
     },
     get(input, context) {
       return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
         const bucket = bucketFor(input);
-        assertKey(input.key);
+        assertKey(input.objectRef);
         (0, import_row_storage_provider_io.assertReportingRowReadBounds)(input);
-        const generation = pinnedGeneration(input.nativeVersion);
+        const generation = pinnedGeneration(input.nativeVersionRef);
         if (generation === null) return null;
-        const file = bucket.file(input.key, { generation });
+        const file = bucket.file(input.objectRef, { generation });
         try {
           if (input.range?.length === 0) {
             const [metadata] = await file.getMetadata();
@@ -180,14 +180,34 @@ function createGcsReportingRowObjectProviderV1(options) {
         }
       });
     },
+    stat(input, context) {
+      return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
+        const bucket = bucketFor(input);
+        assertKey(input.objectRef);
+        const generation = pinnedGeneration(input.nativeVersionRef);
+        if (generation === null) return null;
+        try {
+          const [metadata] = await bucket.file(input.objectRef, { generation }).getMetadata();
+          const size = Number(metadata.size);
+          if (String(metadata.generation) !== generation) return null;
+          if (!Number.isSafeInteger(size) || size < 0) {
+            throw new import_row_storage_errors.ReportingRowStoreError("PROVIDER_UNAVAILABLE", "object metadata is malformed");
+          }
+          return { nativeVersionRef: generation, sizeBytes: size };
+        } catch (error) {
+          if (status(error) === 404) return null;
+          throw error;
+        }
+      });
+    },
     delete(input, context) {
       return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
         const bucket = bucketFor(input);
-        assertKey(input.key);
-        const generation = pinnedGeneration(input.nativeVersion);
+        assertKey(input.objectRef);
+        const generation = pinnedGeneration(input.nativeVersionRef);
         if (generation === null) return "absent";
         try {
-          await bucket.file(input.key, { generation }).delete();
+          await bucket.file(input.objectRef, { generation }).delete();
           return "deleted";
         } catch (error) {
           const code = status(error);

package/dist/lib/reporting/gcs/row-provider.mjs

@@ -24,8 +24,8 @@ function generationOf(metadata) {
   }
   return generation;
 }
-function pinnedGeneration(nativeVersion) {
-  return typeof nativeVersion === "string" && GENERATION.test(nativeVersion) && Number.isSafeInteger(Number(nativeVersion)) ? nativeVersion : null;
+function pinnedGeneration(nativeVersionRef) {
+  return typeof nativeVersionRef === "string" && GENERATION.test(nativeVersionRef) && Number.isSafeInteger(Number(nativeVersionRef)) ? nativeVersionRef : null;
 }
 function assertGcsReportingRowBucketPolicyV1(metadata, prefix) {
   if (!metadata || typeof metadata !== "object") {
@@ -96,8 +96,8 @@ function createGcsReportingRowObjectProviderV1(options) {
     putIfAbsent(input, context) {
       return runReportingRowProviderOperation(context.signal, async () => {
         const bucket = bucketFor(input);
-        assertKey(input.key);
-        const file = bucket.file(input.key);
+        assertKey(input.objectRef);
+        const file = bucket.file(input.objectRef);
         try {
           const bytes = Buffer.from(input.bytes);
           await file.save(bytes, {
@@ -119,24 +119,24 @@ function createGcsReportingRowObjectProviderV1(options) {
         } catch (error) {
           if (status(error) !== 412) throw error;
           context.signal.throwIfAborted();
-          const [existing] = await bucket.file(input.key).getMetadata();
-          return { created: false, nativeVersion: generationOf(existing) };
+          const [existing] = await bucket.file(input.objectRef).getMetadata();
+          return { created: false, nativeVersionRef: generationOf(existing) };
         }
         if (file.metadata?.generation !== void 0) {
-          return { created: true, nativeVersion: generationOf(file.metadata) };
+          return { created: true, nativeVersionRef: generationOf(file.metadata) };
         }
         const [created] = await file.getMetadata();
-        return { created: true, nativeVersion: generationOf(created) };
+        return { created: true, nativeVersionRef: generationOf(created) };
       });
     },
     get(input, context) {
       return runReportingRowProviderOperation(context.signal, async () => {
         const bucket = bucketFor(input);
-        assertKey(input.key);
+        assertKey(input.objectRef);
         assertReportingRowReadBounds(input);
-        const generation = pinnedGeneration(input.nativeVersion);
+        const generation = pinnedGeneration(input.nativeVersionRef);
         if (generation === null) return null;
-        const file = bucket.file(input.key, { generation });
+        const file = bucket.file(input.objectRef, { generation });
         try {
           if (input.range?.length === 0) {
             const [metadata] = await file.getMetadata();
@@ -164,14 +164,34 @@ function createGcsReportingRowObjectProviderV1(options) {
         }
       });
     },
+    stat(input, context) {
+      return runReportingRowProviderOperation(context.signal, async () => {
+        const bucket = bucketFor(input);
+        assertKey(input.objectRef);
+        const generation = pinnedGeneration(input.nativeVersionRef);
+        if (generation === null) return null;
+        try {
+          const [metadata] = await bucket.file(input.objectRef, { generation }).getMetadata();
+          const size = Number(metadata.size);
+          if (String(metadata.generation) !== generation) return null;
+          if (!Number.isSafeInteger(size) || size < 0) {
+            throw new ReportingRowStoreError("PROVIDER_UNAVAILABLE", "object metadata is malformed");
+          }
+          return { nativeVersionRef: generation, sizeBytes: size };
+        } catch (error) {
+          if (status(error) === 404) return null;
+          throw error;
+        }
+      });
+    },
     delete(input, context) {
       return runReportingRowProviderOperation(context.signal, async () => {
         const bucket = bucketFor(input);
-        assertKey(input.key);
-        const generation = pinnedGeneration(input.nativeVersion);
+        assertKey(input.objectRef);
+        const generation = pinnedGeneration(input.nativeVersionRef);
         if (generation === null) return "absent";
         try {
-          await bucket.file(input.key, { generation }).delete();
+          await bucket.file(input.objectRef, { generation }).delete();
           return "deleted";
         } catch (error) {
           const code = status(error);

package/dist/lib/reporting/ledger/change-feed.d.mts

@@ -10,9 +10,17 @@
  * the reading snapshot's `xmin`, so a slow commit is never skipped. Account
  * readers order by `seq` and end the page before the first change at or above
  * that `xmin`. Use exactly one writer SDK per ledger database.
+ *
+ * @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_LEDGER_CHANGES_MIGRATION: 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 type ReportingChangeKindV1 = 'obligation' | 'revision' | 'adjustment' | 'retirement';
+/**
+ * @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 ReportingChangeRecordV1 {
     kind: ReportingChangeKindV1;
     record_id: string;
@@ -20,6 +28,9 @@ export interface ReportingChangeRecordV1 {
     account_id: string;
     recorded_at: 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 ReportingChangesPageV1 {
     records: ReportingChangeRecordV1[];
     /** Pass back to resume. Always present; equal to the input when nothing new committed. */
@@ -33,9 +44,19 @@ interface ChangeCursorV1 {
     /** Deployment-wide feeds only: the writing transaction of the last record returned. */
     xid?: 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 encodeReportingChangeCursorV1(cursor: ChangeCursorV1): 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 decodeReportingChangeCursorV1(value: string, account: string | null): ChangeCursorV1;
-/** Thrown when a change cursor is older than the retained change history. */
+/**
+ * Thrown when a change cursor is older than the retained change history.
+ *
+ * @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 ReportingChangeCursorExpiredError extends Error {
     readonly cursor?: string | undefined;
     readonly code: "CURSOR_EXPIRED";

package/dist/lib/reporting/ledger/change-feed.d.ts

@@ -10,9 +10,17 @@
  * the reading snapshot's `xmin`, so a slow commit is never skipped. Account
  * readers order by `seq` and end the page before the first change at or above
  * that `xmin`. Use exactly one writer SDK per ledger database.
+ *
+ * @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_LEDGER_CHANGES_MIGRATION: 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 type ReportingChangeKindV1 = 'obligation' | 'revision' | 'adjustment' | 'retirement';
+/**
+ * @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 ReportingChangeRecordV1 {
     kind: ReportingChangeKindV1;
     record_id: string;
@@ -20,6 +28,9 @@ export interface ReportingChangeRecordV1 {
     account_id: string;
     recorded_at: 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 ReportingChangesPageV1 {
     records: ReportingChangeRecordV1[];
     /** Pass back to resume. Always present; equal to the input when nothing new committed. */
@@ -33,9 +44,19 @@ interface ChangeCursorV1 {
     /** Deployment-wide feeds only: the writing transaction of the last record returned. */
     xid?: 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 encodeReportingChangeCursorV1(cursor: ChangeCursorV1): 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 decodeReportingChangeCursorV1(value: string, account: string | null): ChangeCursorV1;
-/** Thrown when a change cursor is older than the retained change history. */
+/**
+ * Thrown when a change cursor is older than the retained change history.
+ *
+ * @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 ReportingChangeCursorExpiredError extends Error {
     readonly cursor?: string | undefined;
     readonly code: "CURSOR_EXPIRED";

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

@@ -1,3 +1,14 @@
+/**
+ * Reliable Reporting ledger, row storage, change feed, managed-delivery runtime and router.
+ *
+ * Exports tagged `@experimental` (storage, rows, change feed, managed delivery, notification activity)
+ * may change in minor releases. The protocol-facing handlers, producer, status ingest, health,
+ * coverage, lifecycle and schedule helpers follow normal semver.
+ *
+ * Stability policy: https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ *
+ * @packageDocumentation
+ */
 export * from './types.mjs';
 export * from './health.mjs';
 export * from './coverage.mjs';

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

@@ -1,3 +1,14 @@
+/**
+ * Reliable Reporting ledger, row storage, change feed, managed-delivery runtime and router.
+ *
+ * Exports tagged `@experimental` (storage, rows, change feed, managed delivery, notification activity)
+ * may change in minor releases. The protocol-facing handlers, producer, status ingest, health,
+ * coverage, lifecycle and schedule helpers follow normal semver.
+ *
+ * Stability policy: https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
+ *
+ * @packageDocumentation
+ */
 export * from './types';
 export * from './health';
 export * from './coverage';

package/dist/lib/reporting/ledger/managed-postgres.d.mts

@@ -7,8 +7,13 @@ import { type ReportingDestinationAuthorizationV1, type ReportingDestinationRevo
  * Additive migration owned by #2944. It intentionally does not alter the Core
  * tables so the #2943 notification/activity bridge can evolve that schema
  * independently. Apply after REPORTING_LEDGER_MIGRATION in the same schema.
+ *
+ * @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_MANAGED_DELIVERY_MIGRATION: 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 PostgresReportingManagedDeliveryStoreOptions {
     /** Transactional reporting outbox used for successful delivery-ready events. */
     notificationActivityPort?: ReportingLedgerNotificationActivityPortV1<ReportingLedgerTransactionV1>;
@@ -53,6 +58,9 @@ export interface PostgresReportingManagedDeliveryStoreOptions {
      */
     evidenceRetentionDays?: 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 declare class PostgresReportingManagedDeliveryStore implements ReportingManagedDeliveryStore, ReportingObjectWriteStoreV1, ReportingObjectWriteAuthorityStoreV1 {
     private readonly pool;
     private readonly evidenceRetentionDays;

package/dist/lib/reporting/ledger/managed-postgres.d.ts

@@ -7,8 +7,13 @@ import { type ReportingDestinationAuthorizationV1, type ReportingDestinationRevo
  * Additive migration owned by #2944. It intentionally does not alter the Core
  * tables so the #2943 notification/activity bridge can evolve that schema
  * independently. Apply after REPORTING_LEDGER_MIGRATION in the same schema.
+ *
+ * @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_MANAGED_DELIVERY_MIGRATION: 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 PostgresReportingManagedDeliveryStoreOptions {
     /** Transactional reporting outbox used for successful delivery-ready events. */
     notificationActivityPort?: ReportingLedgerNotificationActivityPortV1<ReportingLedgerTransactionV1>;
@@ -53,6 +58,9 @@ export interface PostgresReportingManagedDeliveryStoreOptions {
      */
     evidenceRetentionDays?: 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 declare class PostgresReportingManagedDeliveryStore implements ReportingManagedDeliveryStore, ReportingObjectWriteStoreV1, ReportingObjectWriteAuthorityStoreV1 {
     private readonly pool;
     private readonly evidenceRetentionDays;

package/dist/lib/reporting/ledger/managed-router.d.mts

@@ -2,7 +2,11 @@ import type { ReportingVerification } from '../../types/index.mjs';
 import { type ReportingDestinationAuthorizationV1, type ReportingDestinationPatternV1, type ReportingManagedDeliveryAdapterV1 } from './managed.mjs';
 import type { ReportingManagedDeliveryBindingV1 } from './types.mjs';
 type VerificationProfile = ReportingVerification['verification_profile'];
-/** Why a delivery, read, revocation or admission could not be routed. */
+/**
+ * Why a delivery, read, revocation or admission could not be routed.
+ *
+ * @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 ReportingManagedDeliveryRoutingErrorCodeV1 = 
 /** No route is installed for the pattern and transport. */
 'REPORTING_ROUTE_NOT_FOUND'
@@ -12,10 +16,15 @@ export type ReportingManagedDeliveryRoutingErrorCodeV1 =
  | 'REPORTING_ROUTE_CONTRACT_UNRECORDED'
 /** The binding's verification profile is not one its route can verify. */
  | 'REPORTING_ROUTE_VERIFICATION_UNSUPPORTED';
+/**
+ * @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 ReportingManagedDeliveryRoutingOperationV1 = 'deliver' | 'read' | 'revoke' | 'admit_binding' | 'admit_offering';
 /**
  * Raised by the router before it touches any adapter. The fields are the
  * non-secret routing facts only: no destination, location or credential.
+ *
+ * @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 ReportingManagedDeliveryRoutingErrorV1 extends Error {
     readonly code: ReportingManagedDeliveryRoutingErrorCodeV1;
@@ -33,11 +42,16 @@ export declare class ReportingManagedDeliveryRoutingErrorV1 extends Error {
  * Raised by `router.probe()` when at least one route's probe failed. Carries
  * the ids of the failing routes and nothing else from the provider; the
  * individual errors are on `cause` (an `AggregateError`) for seller logs only.
+ *
+ * @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 ReportingManagedDeliveryProbeErrorV1 extends Error {
     readonly failedRouteIds: readonly string[];
     constructor(failedRouteIds: readonly string[], errors: readonly 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 ReportingManagedDeliveryRouteV1 {
     /** Stable id used in per-route counts and probe failures. Lowercase token, at most 64 characters. */
     id: string;
@@ -53,6 +67,9 @@ export interface ReportingManagedDeliveryRouteV1 {
      */
     adapter: ReportingManagedDeliveryAdapterV1;
 }
+/**
+ * @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 CreateReportingManagedDeliveryAdapterRouterOptionsV1 {
     routes: readonly ReportingManagedDeliveryRouteV1[];
     /**
@@ -70,7 +87,11 @@ export interface CreateReportingManagedDeliveryAdapterRouterOptionsV1 {
      */
     probeTimeoutMilliseconds?: number;
 }
-/** What a router exposes about a route. The adapter itself stays private to the router. */
+/**
+ * What a router exposes about a route. The adapter itself stays private to the router.
+ *
+ * @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 ReportingManagedDeliveryRouteDescriptionV1 {
     readonly id: string;
     readonly match: Readonly<{
@@ -82,6 +103,8 @@ export interface ReportingManagedDeliveryRouteDescriptionV1 {
 /**
  * A `ReportingManagedDeliveryAdapterV1` that dispatches to one adapter per
  * (pattern, transport). The optional hooks are always present on a router.
+ *
+ * @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 ReportingManagedDeliveryAdapterRouterV1 extends ReportingManagedDeliveryAdapterV1 {
     readonly routes: readonly ReportingManagedDeliveryRouteDescriptionV1[];
@@ -118,6 +141,8 @@ export interface ReportingManagedDeliveryAdapterRouterV1 extends ReportingManage
  *   authorization generation. It never fans out.
  * - Nothing that cannot be routed reaches an adapter: the router throws a
  *   `ReportingManagedDeliveryRoutingErrorV1` first.
+ *
+ * @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 createReportingManagedDeliveryAdapterRouterV1(options: CreateReportingManagedDeliveryAdapterRouterOptionsV1): ReportingManagedDeliveryAdapterRouterV1;
 export {};

package/dist/lib/reporting/ledger/managed-router.d.ts

@@ -2,7 +2,11 @@ import type { ReportingVerification } from '../../types';
 import { type ReportingDestinationAuthorizationV1, type ReportingDestinationPatternV1, type ReportingManagedDeliveryAdapterV1 } from './managed';
 import type { ReportingManagedDeliveryBindingV1 } from './types';
 type VerificationProfile = ReportingVerification['verification_profile'];
-/** Why a delivery, read, revocation or admission could not be routed. */
+/**
+ * Why a delivery, read, revocation or admission could not be routed.
+ *
+ * @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 ReportingManagedDeliveryRoutingErrorCodeV1 = 
 /** No route is installed for the pattern and transport. */
 'REPORTING_ROUTE_NOT_FOUND'
@@ -12,10 +16,15 @@ export type ReportingManagedDeliveryRoutingErrorCodeV1 =
  | 'REPORTING_ROUTE_CONTRACT_UNRECORDED'
 /** The binding's verification profile is not one its route can verify. */
  | 'REPORTING_ROUTE_VERIFICATION_UNSUPPORTED';
+/**
+ * @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 ReportingManagedDeliveryRoutingOperationV1 = 'deliver' | 'read' | 'revoke' | 'admit_binding' | 'admit_offering';
 /**
  * Raised by the router before it touches any adapter. The fields are the
  * non-secret routing facts only: no destination, location or credential.
+ *
+ * @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 ReportingManagedDeliveryRoutingErrorV1 extends Error {
     readonly code: ReportingManagedDeliveryRoutingErrorCodeV1;
@@ -33,11 +42,16 @@ export declare class ReportingManagedDeliveryRoutingErrorV1 extends Error {
  * Raised by `router.probe()` when at least one route's probe failed. Carries
  * the ids of the failing routes and nothing else from the provider; the
  * individual errors are on `cause` (an `AggregateError`) for seller logs only.
+ *
+ * @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 ReportingManagedDeliveryProbeErrorV1 extends Error {
     readonly failedRouteIds: readonly string[];
     constructor(failedRouteIds: readonly string[], errors: readonly 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 ReportingManagedDeliveryRouteV1 {
     /** Stable id used in per-route counts and probe failures. Lowercase token, at most 64 characters. */
     id: string;
@@ -53,6 +67,9 @@ export interface ReportingManagedDeliveryRouteV1 {
      */
     adapter: ReportingManagedDeliveryAdapterV1;
 }
+/**
+ * @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 CreateReportingManagedDeliveryAdapterRouterOptionsV1 {
     routes: readonly ReportingManagedDeliveryRouteV1[];
     /**
@@ -70,7 +87,11 @@ export interface CreateReportingManagedDeliveryAdapterRouterOptionsV1 {
      */
     probeTimeoutMilliseconds?: number;
 }
-/** What a router exposes about a route. The adapter itself stays private to the router. */
+/**
+ * What a router exposes about a route. The adapter itself stays private to the router.
+ *
+ * @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 ReportingManagedDeliveryRouteDescriptionV1 {
     readonly id: string;
     readonly match: Readonly<{
@@ -82,6 +103,8 @@ export interface ReportingManagedDeliveryRouteDescriptionV1 {
 /**
  * A `ReportingManagedDeliveryAdapterV1` that dispatches to one adapter per
  * (pattern, transport). The optional hooks are always present on a router.
+ *
+ * @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 ReportingManagedDeliveryAdapterRouterV1 extends ReportingManagedDeliveryAdapterV1 {
     readonly routes: readonly ReportingManagedDeliveryRouteDescriptionV1[];
@@ -118,6 +141,8 @@ export interface ReportingManagedDeliveryAdapterRouterV1 extends ReportingManage
  *   authorization generation. It never fans out.
  * - Nothing that cannot be routed reaches an adapter: the router throws a
  *   `ReportingManagedDeliveryRoutingErrorV1` first.
+ *
+ * @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 createReportingManagedDeliveryAdapterRouterV1(options: CreateReportingManagedDeliveryAdapterRouterOptionsV1): ReportingManagedDeliveryAdapterRouterV1;
 export {};